@beingmartinbmc/ojas 0.2.0

package/docs/MCP.md

@@ -0,0 +1,614 @@
+# MCP Server
+
+Ojas ships an MCP server that exposes 18 agent-health tools to Claude Code, Cursor, Windsurf, and other MCP-compatible clients.
+
+Each IDE session gets its own multi-agent registry. Every `agent_id` maps to an Ojas instance and `HealthContract`. Unknown agents can auto-register with conservative defaults so tools can be called without manual setup — but production deployments should disable that and use the allowlist (see [Environment variables](#env)).
+
+| Section | What's inside |
+|---|---|
+| [Build](#build) | Compile the MCP server entry point |
+| [MCP Configuration](#mcp-config) | Claude Code, Cursor, Windsurf wiring |
+| [Environment variables](#env) | Operational knobs for shared deployments |
+| [A typical first session](#first-session) | Six tool calls that show the full loop |
+| [Tools — Setup & telemetry](#tools-setup) | `ojas_register_agent`, `ojas_ingest_trace` |
+| [Tools — Decisions](#tools-decisions) | `ojas_get_health`, `ojas_is_agent_fit_to_continue` |
+| [Tools — Context safety](#tools-context) | `ojas_score_context`, `ojas_build_context`, `ojas_scan_for_injection` |
+| [Tools — Output quality & routing](#tools-output) | `ojas_detect_hallucination`, `ojas_recommend_model_route`, `ojas_distill_response`, `ojas_record_task_outcome` |
+| [Tools — Memory hygiene](#tools-memory) | `ojas_audit_memory`, `ojas_validate_memory_write`, `ojas_consolidate_memory` |
+| [Tools — Repair](#tools-repair) | `ojas_diagnose_failure`, `ojas_run_recovery` |
+| [Tools — Reporting & handoff](#tools-reporting) | `ojas_generate_handoff`, `ojas_generate_health_report` |
+| [Response envelope](#envelope) | Standard fields wrapping every tool reply |
+| [Suggested usage loop](#usage-loop) | The canonical call order |
+| [Verification](#verification) | One-line smoke test for a fresh install |
+
+---
+
+<a id="build"></a>
+## Build
+
+```bash
+npm install
+npm run build
+```
+
+Compiled entry point:
+
+```text
+dist/mcp/server.js
+```
+
+Replace `/absolute/path/to/ojas` in the examples below with your local clone path.
+
+---
+
+<a id="mcp-config"></a>
+## MCP Configuration
+
+### Claude Code
+
+Project-level `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "ojas": {
+      "command": "node",
+      "args": ["/absolute/path/to/ojas/dist/mcp/server.js"],
+      "env": {
+        "OJAS_AGENT_ID": "claude-code"
+      }
+    }
+  }
+}
+```
+
+Or with the CLI:
+
+```bash
+claude mcp add ojas -- node /absolute/path/to/ojas/dist/mcp/server.js
+```
+
+### Cursor
+
+Project-level `.cursor/mcp.json` or global `~/.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "ojas": {
+      "command": "node",
+      "args": ["/absolute/path/to/ojas/dist/mcp/server.js"],
+      "env": {
+        "OJAS_AGENT_ID": "cursor"
+      }
+    }
+  }
+}
+```
+
+### Windsurf
+
+`~/.codeium/windsurf/mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "ojas": {
+      "command": "node",
+      "args": ["/absolute/path/to/ojas/dist/mcp/server.js"],
+      "env": {
+        "OJAS_AGENT_ID": "windsurf"
+      }
+    }
+  }
+}
+```
+
+---
+
+<a id="env"></a>
+## Environment variables
+
+| Variable | Default | Effect |
+|---|---|---|
+| `OJAS_AGENT_ID` | unset | Pre-register a single agent at startup with conservative defaults. Additional agents can still be added via `ojas_register_agent`. |
+| `OJAS_DISABLE_AUTO_REGISTER` | unset | Set to `1` to reject MCP calls whose `agent_id` has not been explicitly registered. Recommended for production. |
+| `OJAS_MAX_AGENTS` | `256` | Hard cap on simultaneously-tracked agents. Once full, `ojas_register_agent` throws rather than silently evicting. |
+| `OJAS_ALLOWED_AGENT_IDS` | unset | Comma-separated allowlist of `agent_id`s. When set, any registration or auto-register attempt for an id outside this list is rejected. |
+| `OJAS_ALLOW_REPLACE_EXISTING` | unset | Set to `1` to permit `register_agent(replace_existing=true)`. **Disabled by default** because replacement wipes the agent's accumulated Ojas state. |
+| `OJAS_TRUSTED_SINGLE_TENANT` | unset | Acknowledgement that the operator understands the no-auth single-tenant trust model. Suppresses the loud stderr warning emitted at startup; does **not** add authentication. |
+
+> `register_agent` rejects a duplicate `agent_id` by default. To replace an existing agent (and discard its accumulated Ojas state) the caller must pass `replace_existing: true` **and** the registry must be configured with `allowReplaceExisting: true` (or the server started with `OJAS_ALLOW_REPLACE_EXISTING=1`). Silently overwriting a long-lived agent's history would erase the very telemetry the system exists to capture.
+
+---
+
+<a id="trust-boundary"></a>
+## Local-only stdio trust boundary
+
+The MCP server is designed for **local stdio use**. It assumes the MCP
+host that starts the process is trusted. Agent IDs are routing
+identifiers, **not credentials**, and there is no per-call authentication
+inside the server — there is no portable stdio auth channel for one to
+hook into. This is the intended trust boundary for v0.2, not a deferred
+fix; see the [security non-goals](./SECURITY.md#security-non-goals-for-v02).
+
+Recommended locked-down local configuration:
+
+```bash
+OJAS_TRUSTED_SINGLE_TENANT=1      # acknowledge the trust model (silences warning)
+OJAS_DISABLE_AUTO_REGISTER=1      # reject unknown agent_id, force explicit registration
+OJAS_ALLOWED_AGENT_IDS=my-agent   # hard allowlist
+OJAS_MAX_AGENTS=1                 # one agent per process
+# do NOT set OJAS_ALLOW_REPLACE_EXISTING unless intentionally resetting state
+```
+
+Operationally:
+
+- Run **one process per trusted user / workspace**.
+- Do **not** expose this server over a network or share one process across untrusted users.
+- For multi-user or network deployments, front Ojas with an authenticated MCP gateway, or run one isolated Ojas process per user / workspace.
+
+If Ojas ever ships a non-stdio transport (HTTP, SSE, streamable-HTTP),
+that transport will fail closed unless auth is configured.
+
+---
+
+<a id="first-session"></a>
+## A typical first session
+
+A new agent typically issues this exact sequence during one task. Each step shows the request shape (`→`) and the most-relevant response fields (`←`). The standard envelope (`status`, `correlation_id`, `affected_modules`, …) is present on every response but omitted here for brevity.
+
+```jsonc
+// 1. Register the agent and create its health contract.
+→ ojas_register_agent
+{
+  "agent_id": "research-agent",
+  "risk_level": "medium",
+  "health_thresholds": { "minimum_ojas_score": 80 },
+  "recovery_policy": { "on_prompt_injection": "quarantine_input" }
+}
+← {
+  "registered": true,
+  "initial_ojas_score": 100,
+  "health_state": "healthy",
+  "health_contract": { "agent_id": "research-agent", "health_contract_id": "contract_..." }
+}
+
+// 2. Filter retrieved content through Raksha + Aahar before reading it.
+→ ojas_build_context
+{
+  "agent_id": "research-agent",
+  "task": "Compare vector databases for enterprise RAG",
+  "max_tokens": 4096,
+  "candidate_items": [ /* 17 retrieved items */ ]
+}
+← {
+  "context_bundle_id": "bundle_...",
+  "context_health_score": 87,
+  "included_items": 7,
+  "excluded_items": 10,
+  "retained_token_ratio": 0.42,   // accepted_tokens / total_tokens
+  "compression_ratio": 0.42,      // legacy alias for retained_token_ratio
+  "warnings": ["excluded 2 stale items", "quarantined 1 injection attempt"],
+  "context": "[#ctx-001 | analyst_report] Pinecone offers managed scaling ..."
+}
+
+// 3. Stream a trace every time the agent calls a tool.
+→ ojas_ingest_trace
+{
+  "agent_id": "research-agent",
+  "event_type": "tool_call_failed",
+  "data": { "tool_name": "web_search", "error_type": "timeout", "latency_ms": 8000 }
+}
+← {
+  "accepted": true,
+  "event_id": "evt_...",
+  "trace_id": "trace_...",
+  "health_impact_detected": true,
+  "recommended_action": "diagnose_tool_failure"
+}
+
+// 4. Before the next risky action, ask the gate.
+→ ojas_is_agent_fit_to_continue
+{
+  "agent_id": "research-agent",
+  "task_risk_level": "high",
+  "planned_next_action": "call_web_search"
+}
+← {
+  "fit_to_continue": false,
+  "confidence": 0.62,
+  "health_state": "watch",
+  "ojas_score": 62,
+  "required_score": 90,
+  "risks": ["recent tool timeout"],
+  "required_actions_before_continue": ["run ojas_run_recovery to lift score above threshold"],
+  "safe_mode_required": false
+}
+
+// 5. Not fit — diagnose, then run recovery in recommend mode (the default).
+→ ojas_diagnose_failure
+{
+  "agent_id": "research-agent",
+  "failure_description": "web_search timed out 3 times in 60 seconds"
+}
+← {
+  "diagnosis_id": "chikitsa-...",
+  "primary_cause": "loop",
+  "secondary_causes": ["high_cost_pressure"],
+  "recommended_repair": ["context_reset", "plan_regeneration"],
+  "severity": "warning"
+}
+
+→ ojas_run_recovery
+{ "agent_id": "research-agent", "recovery_type": "tool_failure_loop" }
+← {
+  "recovery_id": "recovery_...",
+  "mode": "recommend",
+  "outcome": "recommended",
+  "actions": [
+    { "action": "freeze_memory_writes",       "reason": "avoid storing degraded loop behavior" },
+    { "action": "reset_plan",                 "reason": "agent is stuck in a repeated tool-call loop" },
+    { "action": "generate_fallback_response", "reason": "underlying tool unavailable after repeated attempts" }
+  ]
+}
+
+// 6. After applying recovery, generate the session report.
+→ ojas_generate_health_report
+{ "agent_id": "research-agent", "scope": "session" }
+← {
+  "overall_ojas_score": 87,
+  "module_scores": { "aahar": 91, "nidra": 78, "vyayam": 97, "raksha": 93, "agni": 96, "pulse": 68, "chikitsa": 72 },
+  "summary": "research-agent recovered from a tool-failure loop; healthy to resume.",
+  "top_risks": ["over_retrieval"],
+  "recommended_next_steps": ["compress_context"]
+}
+```
+
+---
+
+<a id="tools-setup"></a>
+## 1. Setup & telemetry
+
+Every interaction starts here.
+
+| Tool | Purpose | Key input | Key output |
+|---|---|---|---|
+| `ojas_register_agent` | Create the agent's health contract | `agent_id`, `risk_level`, `health_thresholds`, `recovery_policy`, optional `allowed_tools[]`, optional `replace_existing` | `registered`, `health_contract`, `initial_ojas_score`, `health_state` |
+| `ojas_ingest_trace` | Stream a runtime event into Ojas | `event_type` (one of 17), `data` | `accepted`, `event_id`, `health_impact_detected`, `policy_violation`, `recommended_action` |
+
+> When a contract sets `allowed_tools`, any `ojas_ingest_trace` call with `data.tool_name` outside that list is recorded as a `tool_policy_violation`. The response sets `accepted: false`, `policy_violation: true`, `health_impact_detected: true`, `recommended_action: "review_tool_policy_violation"`, and flags `requires_human_review: true` in the envelope. The tool name is also reflected in the trace's `error` field so Chikitsa picks it up for diagnosis.
+
+Supported `event_type` values:
+
+```text
+agent_input        agent_output
+tool_call_started  tool_call_succeeded  tool_call_failed
+retrieval_result   memory_read          memory_write
+failure            latency_measurement  token_usage
+user_correction    planning_loop        fallback
+policy_violation   prompt_injection_detected   context_overload_detected
+```
+
+Each event is routed to the relevant modules — for example `tool_call_failed` flows to Agni (cost), Pulse (telemetry), and Chikitsa (diagnosis), and the response includes the recommended follow-up.
+
+---
+
+<a id="tools-decisions"></a>
+## 2. Decisions
+
+Current state, fitness gating, and operational fitness.
+
+| Tool | Purpose | Key input | Key output |
+|---|---|---|---|
+| `ojas_get_health` | Current Ojas snapshot | `agent_id`, `include_modules`, `include_recent_events` | `ojas_score`, `health_state`, `module_scores`, `active_risks`, `recommended_actions` |
+| **`ojas_is_agent_fit_to_continue`** | **Signature gate.** Should the agent proceed? | `agent_id`, `task_risk_level`, `planned_next_action` | `fit_to_continue`, `confidence`, `required_score`, `required_actions_before_continue`, `safe_mode_required` |
+
+The fitness gate answers the operational question most agent frameworks don't ask:
+
+> Is this agent cognitively healthy enough to proceed?
+
+The required score scales with `task_risk_level`: **medium** uses the contract's `minimum_ojas_score`, **high** adds +10, **critical** adds +20. Critical-risk tasks on a non-healthy agent flip `safe_mode_required` to `true` and `requires_human_review` to `true` in the envelope.
+
+---
+
+<a id="tools-context"></a>
+## 3. Context safety
+
+Everything the agent reads passes through one of these.
+
+| Tool | Purpose | Key input | Key output |
+|---|---|---|---|
+| `ojas_score_context` | Per-item nutrition + threat scoring | `agent_id`, `task`, `context_items[]` | `context_health_score`, `item_scores[]` (with `relevance_score`, `relevance_source` (`caller`/`lexical_fallback`), `freshness_score`, `trust_score`, `risk_score`, `recommendation`), `warnings` |
+| `ojas_build_context` | Assemble a clean bundle within a token budget | `agent_id`, `task`, `max_tokens`, `risk_level`, `candidate_items[]` | `context_bundle_id`, `included_ids`, `retained_token_ratio` (and legacy `compression_ratio = retained_token_ratio`), `warnings`, `context` |
+| `ojas_scan_for_injection` | One-shot threat scan on a single piece of content | `agent_id`, `source_type`, `content`, `intended_use` | `injection_detected`, `risk_score`, `attack_type`, `allowed_for_context`, `allowed_for_memory`, `reasons` |
+
+`scan_for_injection` is the right tool when you want a verdict on a single string (e.g. one retrieved page) without putting it through Aahar. `score_context` and `build_context` are batch tools that run the same Raksha scan plus Aahar nutrition.
+
+---
+
+<a id="tools-output"></a>
+## 4. Output quality & routing
+
+These tools operate after or around generation: checking the answer, trimming response load, and feeding success/failure learning back into Agni and Chikitsa.
+
+| Tool | Purpose | Key input | Key output |
+|---|---|---|---|
+| `ojas_detect_hallucination` | Score an agent output for hallucination risk | `output`, optional `prompt`, `samples[]`, `context[]` | `hallucination_detected`, `risk_score`, `confidence`, `detector`, `reasons`, `claims[]`, `abstention` |
+| `ojas_recommend_model_route` | Decide whether a task class can use a cheap route | `task_class`, optional `include_report` | `route` (`cheap` / `flagship`), `reason`, `observations`, `success_ci`, `router_report?` |
+| `ojas_distill_response` | Remove low-signal filler from an output | `response`, optional `intensity` (`lite` / `full` / `ultra`) | `distilled_response`, `tokens_removed`, `chars_removed`, `removed_categories`, `distiller` |
+| `ojas_record_task_outcome` | Feed task success/failure back into routing and velocity stats | `task_id`, `succeeded`, `duration_ms`, optional `task_class`, `category`, `completed_at` | `recorded`, `route_after_recording`, `velocity_stats` |
+
+`recommend_model_route` is deliberately fail-closed: sparse data, safety classes such as `security` / `auth`, or a weak Wilson confidence lower bound all return `flagship`. `record_task_outcome` is how MCP clients teach that router over time; it also updates Chikitsa's rolling velocity window for handoffs.
+
+`distill_response` uses the configured Agni distiller by default and updates `lifetime_output_tokens_saved`. If a per-call `intensity` is supplied, Ojas uses a temporary default distiller at that intensity and reports `lifetime_counter_updated: false`.
+
+---
+
+<a id="tools-memory"></a>
+## 5. Memory hygiene
+
+Memory is a living organ; these tools curate it.
+
+| Tool | Purpose | Key input | Key output |
+|---|---|---|---|
+| `ojas_audit_memory` | Audit the agent's memory store | `agent_id`, `scope`, `include_recommendations` | `memory_health_score`, `issues` (stale / duplicate / conflicting / high_risk / low_usefulness), `recommended_actions` |
+| **`ojas_validate_memory_write`** | Policy gate before a memory commit | `candidate_memory` (`content`, `source`, `confidence`), `reason_for_write` | `allowed`, `memory_status` (`committed` / `candidate` / `session_note` / `rejected`), `reason`, `risk_score` |
+| `ojas_consolidate_memory` | Run a Nidra cycle over recent traces | `consolidation_depth`, `allow_new_memories`, `allow_memory_pruning`, `include_failure_reflection` | `consolidation_id`, `cycle_status`, `memories[]` (proposed), `memories_to_prune`, `lessons_extracted`, `drift_reduction` |
+
+`validate_memory_write` is deliberately conservative by default:
+
+```text
+confidence ≥ 0.75  +  no Raksha hit   →  committed
+confidence ≥ 0.50  +  no Raksha hit   →  candidate     (not yet committed)
+confidence < 0.50                     →  session_note  (scoped to this session)
+any Raksha hit (risk_score > 0.5)     →  rejected
+```
+
+`consolidate_memory` **proposes** memories but does not commit them unless `allow_new_memories: true`. The default is `false` — memory writes are dangerous and should require explicit opt-in.
+
+- A preview run emits a `recovery_cycle_previewed` event and returns `cycle_status: "preview"`, `health_after_estimated: true`. The unprocessed-trace set is untouched, so calling `consolidate_memory` twice with `allow_new_memories: false` is guaranteed to be a no-op.
+- A commit run emits `recovery_cycle_completed` and returns `cycle_status: "committed"`, `health_after_estimated: false`. The bound agent's `injectMemory()` is invoked for every memory before Nidra commits — see the SDK note below.
+
+> **SDK transactionality:** when you bind an `AgentAdapter` and call `Ojas.recover()`, the cycle runs as `analyse → injectMemory(...) → commit`. If any `injectMemory` throws, Nidra state is **not** mutated: no traces are marked processed, no memories are persisted, and a `recovery_injection_failed` pulse event explains the abort. This guarantees the agent's view of memory and Ojas's view stay in sync.
+
+---
+
+<a id="tools-repair"></a>
+## 6. Repair
+
+Diagnose failures and apply structured recovery.
+
+| Tool | Purpose | Key input | Key output |
+|---|---|---|---|
+| `ojas_diagnose_failure` | Chikitsa classifies a failure | `agent_id`, `failure_description`, `failure_type?`, `severity` | `diagnosis_id`, `primary_cause`, `secondary_causes`, `recommended_repair`, `severity` |
+| **`ojas_run_recovery`** | Execute a recovery protocol | `recovery_type`, `mode` (`observe` / `recommend` / `apply`), `allowed_actions?` | `recovery_id`, `mode`, `outcome` (`recommended` / `applied` / `instructed` / `no_effect` / `requires_human_review`), `actions[]`, `mutated_actions[]`, `instruction_actions[]`, `skipped_actions[]`, `applied_actions[]` (deprecated alias for durable mutations), `ojas_score_before`, `ojas_score_after`, `ojas_score_delta` |
+
+`run_recovery` is safe-by-default: `mode` defaults to `recommend`, so the tool returns the action plan without executing it. In `apply` mode, Ojas separates durable mutations from caller instructions: `enter_safe_mode` appears under `mutated_actions`, advisory steps such as `compress_context` appear under `instruction_actions`, and `human_escalation` appears under `skipped_actions`. The legacy `applied_actions` field is retained for one release as a deprecated alias for `mutated_actions` only.
+
+`recovery_type` values:
+
+```text
+tool_failure_loop   context_overload   prompt_injection
+memory_conflict     hallucination      high_cost_pressure
+unknown
+```
+
+Recovery action vocabulary (also reusable as `allowed_actions`):
+
+```text
+compress_context     reset_plan                freeze_memory_writes
+quarantine_input     generate_fallback_response
+enter_safe_mode      human_escalation
+reduce_tool_calls    switch_to_cached_sources
+```
+
+---
+
+<a id="tools-reporting"></a>
+## 7. Reporting & handoff
+
+Human-readable continuity and summary tools.
+
+| Tool | Purpose | Key input | Key output |
+|---|---|---|---|
+| `ojas_generate_handoff` | Markdown handoff for another agent/session | `focus`, `pending_tasks[]`, `completed_tasks[]`, `notes[]`, `include_velocity` | `handoff_markdown`, `generated_at`, `pending_count`, `completed_count`, `velocity_stats` |
+| `ojas_generate_health_report` | Executive summary for dashboards / release gates / postmortems | `agent_id`, `scope`, `report_type`, `include_recommendations` | `report_id`, `overall_ojas_score`, `health_state`, `module_scores`, `summary`, `top_risks`, `recommended_next_steps` |
+
+Use `generate_handoff` when work is moving between agents or sessions. Use `generate_health_report` at session end, on a periodic cron, or as a CI release gate. `scope` accepts `current`, `session`, or `last_24h`; `report_type` accepts `executive_summary` or `technical`.
+
+---
+
+<a id="session-isolation"></a>
+## Session isolation
+
+Ojas MCP tools accept an optional `session_id` argument. Calls with the same
+`agent_id` but different `session_id`s receive separate Ojas runtime state:
+trace windows, memories, tool-outcome history, recovery cycles, safe-mode
+flags, and health snapshots are isolated per session. Omitting `session_id`
+uses the backward-compatible default session.
+
+Every response from a session-aware tool surfaces this honestly:
+
+```json
+{
+  "session_id": "sess_abc",
+  "session_scope_supported": true
+}
+```
+
+When `OJAS_DB_PATH=/path/to/ojas.sqlite` is set, the registry persists those
+session snapshots to SQLite and hydrates them on server restart.
+
+---
+
+<a id="error-semantics"></a>
+## Error semantics: structured envelopes vs MCP protocol errors
+
+Ojas distinguishes two error paths and clients should handle both.
+
+**1. Structured `failed` envelope (`status: 'failed'`).** Any exception
+raised *inside* an Ojas tool handler — including typed `OjasError`s and
+unexpected throws — is caught by `safeHandler` and returned as a normal
+tool response with this shape:
+
+```json
+{
+  "status": "failed",
+  "accepted": false,
+  "error": "Agent 'x' is already registered. ...",
+  "error_class": "ojas_register_agent_error",
+  "error_code": "policy_violation",
+  "requires_human_review": false
+}
+```
+
+`error_code` is one of `invalid_input`, `policy_violation`, `not_found`,
+or `internal_error`. Only `internal_error` defaults to
+`requires_human_review: true` — validation and policy refusals are
+caller-side problems and should be surfaced in the client UI, not the
+operator pager.
+
+**2. MCP-protocol-level error.** Input that fails the tool's Zod
+`inputSchema` (e.g. a string where a number was required, an unknown
+`event_type`, a non-ISO-8601 `created_at`) is rejected by the MCP SDK
+*before* the handler runs. That arrives at the client as an MCP protocol
+error, not as a `status: 'failed'` envelope, because `safeHandler` has
+no opportunity to wrap it.
+
+In practice this means MCP clients need two error-handling paths:
+
+- check `response.status === 'failed'` first to detect tool-level errors;
+- catch transport / protocol errors as a separate branch for schema
+  rejection and SDK-internal failures.
+
+The split is intentional. Loosening schemas to let everything reach the
+handler would weaken the input contract and force every tool to
+re-implement validation. Documenting the split here so clients aren't
+surprised.
+
+---
+
+<a id="envelope"></a>
+## Response envelope
+
+Every MCP tool returns a standard envelope merged with tool-specific fields.
+
+```jsonc
+{
+  "status": "success | warning | failed",
+  "agent_id": "research_agent_01",
+  "correlation_id": "cor-...",
+  "ojas_score_delta": 0,
+  "affected_modules": ["aahar", "raksha"],
+  "events_created": ["evt_..."],
+  "recommended_next_actions": ["compress_context"],
+  "requires_human_review": false
+}
+```
+
+`ojas_ingest_trace` also returns these three orthogonal booleans for
+unambiguous client branching (previously folded into `accepted`):
+
+```jsonc
+{
+  "event_recorded": true,       // trace landed in the store
+  "policy_accepted": true,      // health-contract / allowed_tools gates passed
+  "telemetry_accepted": true    // every reported token / cost field parsed cleanly
+}
+```
+
+`accepted` is preserved for backward compatibility and equals
+`policy_accepted` — new code should branch on the three explicit fields.
+
+Tool-specific fields may include:
+
+```text
+ojas_score
+health_state
+fit_to_continue
+required_score
+context_health_score
+injection_detected
+hallucination_detected
+route
+distilled_response
+velocity_stats
+handoff_markdown
+recommended_repair
+recovery_actions
+memory_write_decision
+provenance        // 'full' | 'degraded' on consolidated memories
+```
+
+---
+
+<a id="usage-loop"></a>
+## Suggested usage loop
+
+```text
+register
+  ↓
+ingest_trace
+  ↓
+score_context / build_context
+  ↓
+scan_for_injection on retrieval or tool outputs
+  ↓
+recommend_model_route before model choice
+  ↓
+detect_hallucination / distill_response after generation
+  ↓
+record_task_outcome after completion
+  ↓
+is_agent_fit_to_continue
+  ↓
+if unhealthy: diagnose_failure → run_recovery
+  ↓
+consolidate_memory
+  ↓
+audit_memory
+  ↓
+generate_handoff / generate_health_report
+```
+
+Recommended call points:
+
+- **Before retrieval-augmented work**: call `ojas_score_context` and `ojas_build_context`
+- **After every tool call**: call `ojas_ingest_trace`
+- **Before risky actions**: call `ojas_is_agent_fit_to_continue`
+- **Before model choice**: call `ojas_recommend_model_route`
+- **After generation**: call `ojas_detect_hallucination` and optionally `ojas_distill_response`
+- **After task completion**: call `ojas_record_task_outcome`
+- **Before memory writes**: call `ojas_validate_memory_write`
+- **After failures**: call `ojas_diagnose_failure`, then `ojas_run_recovery`
+- **At session end**: call `ojas_consolidate_memory`, `ojas_generate_handoff`, and `ojas_generate_health_report`
+
+---
+
+<a id="verification"></a>
+## Verification
+
+After registering the server, restart your IDE and ask the assistant:
+
+```text
+Call ojas_register_agent with agent_id=my-coding-agent, then call ojas_is_agent_fit_to_continue with task_risk_level=high.
+```
+
+Expected response:
+
+```json
+{
+  "fit_to_continue": true,
+  "confidence": 0.91,
+  "health_state": "healthy",
+  "ojas_score": 91,
+  "required_score": 80,
+  "risks": [],
+  "required_actions_before_continue": [],
+  "safe_mode_required": false,
+  "status": "success",
+  "agent_id": "my-coding-agent",
+  "correlation_id": "cor-..."
+}
+```