chore: sync from source 0bb7e87

Author: sync-bot

agents/claude-code/hooks/user_prompt_context_saver.py

@@ -20,7 +20,6 @@
 """
 
 import asyncio
-import contextlib
 import ctypes
 import importlib.util
 import io
@@ -129,139 +128,6 @@ def _load_config_loader() -> ModuleType:
 }
 
 
-def _persist_user_prompt_context_id(
-    session_id: str,
-    context_ids: list[int],
-    user_prompt: str,
-) -> None:
-    """Persist stored user-message context_id(s) and verbatim text to AEGIS runtime files.
-
-    Side-effect-only helper used by orchestrator_sequencing_enforcement.py to:
-    1. Append the context_id to the per-session observed_report_ids JSON file
-       (so the orchestrator's `USER REQUEST CONTEXT ID: [N]` references pass
-       the prompt_id_reference_validity validator).
-    2. Write the FIRST stored context_id as plain text to a per-session sidecar
-       file (so the verbatim_relay_check rule can detect when a context_id is
-       available).
-    3. Write the verbatim user prompt text to a per-session sidecar file
-       (`last_user_prompt_text_{session_id}`) so the verbatim_relay_check rule
-       can perform Option D's text-fragment match without round-tripping
-       through the context-server at hook time.
-
-    Reliability hardening: each attempt is wrapped in a retry loop with one
-    retry attempt and a 50 ms backoff between attempts. On persistent failure
-    (both attempts raise), the failure is logged via `log_always(level='ERROR')`
-    -- never raised. The function's contract is silent-side-effect-only so the
-    hook's existing reliability guarantee (never break Claude Code workflow)
-    is preserved.
-
-    Args:
-        session_id: Claude Code session_id (extracted from input_data).
-        context_ids: List of stored context IDs (single entry for non-chunked,
-            multiple for chunked storage).
-        user_prompt: The verbatim user prompt text (for the text sidecar).
-    """
-    if not context_ids:
-        return
-
-    last_err: Exception | None = None
-    for attempt in range(2):  # 1 try + 1 retry
-        try:
-            runtime_dir = Path(os.path.expanduser('~/.claude/aegis/runtime'))
-            runtime_dir.mkdir(parents=True, exist_ok=True)
-            observed_ids_file = runtime_dir / f'observed_report_ids_{session_id}.json'
-            sidecar_file = runtime_dir / f'last_user_prompt_context_id_{session_id}'
-            text_sidecar_file = runtime_dir / f'last_user_prompt_text_{session_id}'
-
-            # Step 1: read existing observed-IDs list, merge new IDs, write atomically.
-            existing_ids: set[int] = set()
-            try:
-                if observed_ids_file.exists():
-                    loaded = json.loads(observed_ids_file.read_text(encoding='utf-8'))
-                    if isinstance(loaded, dict):
-                        loaded_typed = cast(dict[str, Any], loaded)
-                        raw_ids_value = cast(list[Any] | None, loaded_typed.get('report_ids'))
-                        if isinstance(raw_ids_value, list):
-                            for item in raw_ids_value:
-                                if isinstance(item, int):
-                                    existing_ids.add(item)
-                                elif isinstance(item, str) and item.isdigit():
-                                    existing_ids.add(int(item))
-            except Exception:
-                existing_ids = set()
-            merged = sorted(existing_ids | {int(cid) for cid in context_ids})
-
-            # Atomic write of observed-IDs file (tempfile + os.replace).
-            fd1, tmp_obs_str = tempfile.mkstemp(
-                prefix=observed_ids_file.name + '.',
-                suffix='.tmp',
-                dir=str(runtime_dir),
-            )
-            try:
-                with os.fdopen(fd1, 'w', encoding='utf-8') as f:
-                    json.dump({'report_ids': merged}, f, ensure_ascii=False)
-                    f.flush()
-                    os.fsync(f.fileno())
-                os.replace(tmp_obs_str, str(observed_ids_file))
-            except Exception:
-                with contextlib.suppress(Exception):
-                    Path(tmp_obs_str).unlink(missing_ok=True)
-                raise
-
-            # Step 2: write the first context_id to the sidecar (plain text).
-            fd2, tmp_side_str = tempfile.mkstemp(
-                prefix=sidecar_file.name + '.',
-                suffix='.tmp',
-                dir=str(runtime_dir),
-            )
-            try:
-                with os.fdopen(fd2, 'w', encoding='utf-8') as f:
-                    f.write(str(int(context_ids[0])))
-                    f.flush()
-                    os.fsync(f.fileno())
-                os.replace(tmp_side_str, str(sidecar_file))
-            except Exception:
-                with contextlib.suppress(Exception):
-                    Path(tmp_side_str).unlink(missing_ok=True)
-                raise
-
-            # Step 3: write the verbatim user prompt text to the per-session sidecar
-            # so the verbatim_relay_check rule can perform Option D's text-fragment
-            # match without round-tripping through the context-server at hook time.
-            fd3, tmp_text_str = tempfile.mkstemp(
-                prefix=text_sidecar_file.name + '.',
-                suffix='.tmp',
-                dir=str(runtime_dir),
-            )
-            try:
-                with os.fdopen(fd3, 'w', encoding='utf-8') as f:
-                    f.write(user_prompt)
-                    f.flush()
-                    os.fsync(f.fileno())
-                os.replace(tmp_text_str, str(text_sidecar_file))
-            except Exception:
-                with contextlib.suppress(Exception):
-                    Path(tmp_text_str).unlink(missing_ok=True)
-                raise
-            return  # success on first or retry attempt
-        except Exception as e:
-            last_err = e
-            if attempt == 0:
-                time.sleep(0.05)  # 50 ms backoff before single retry
-                continue
-
-    # Persistent failure: log via log_always ERROR; never raise. Use the
-    # existing diagnostic channel so the message reaches the hook log alongside
-    # all other ERROR-level diagnostics in this module.
-    with contextlib.suppress(Exception):
-        log_always(
-            f'Failed to persist user-message context_id(s) to AEGIS runtime after retry: '
-            f'{context_ids}. Last error: '
-            f'{type(last_err).__name__ if last_err else "Unknown"}: {last_err}',
-            level='ERROR',
-        )
-
-
 def _get_log_file() -> Path:
     """
     Get log file location with multiple fallbacks and diagnostic reporting.
@@ -1854,49 +1720,10 @@ def main() -> None:
                 else:
                     log_always(f'SUCCESS: All {total_chunks} chunks stored successfully')
 
-                # Output chunk IDs via additionalContext for orchestrator reference.
-                #
-                # Extract per-chunk context_ids from the `results` array returned by
-                # `_store_chunks_single_connection` (the dict has key `results`, NOT
-                # `chunk_ids`). Each entry is the raw CallToolResult from
-                # `client.call_tool('store_context', ...)`. FastMCP exposes the
-                # context_id either as `result.structured_content['context_id']`
-                # (canonical) or directly on the dict shape after `.structured_content`
-                # extraction. Handle both shapes defensively, mirroring the
-                # extraction in `_store_single_context_async` (lines 762-767).
+                # Output chunk IDs via additionalContext for orchestrator reference
                 if config.get('output_context_id', True):
-                    chunk_ids: list[int] = []
-                    results_list = cast(list[Any], result.get('results', []))
-                    for entry_any in results_list:
-                        if isinstance(entry_any, dict) and 'error' in cast(dict[str, Any], entry_any):
-                            continue
-                        candidate: Any = None
-                        structured: Any = getattr(cast(Any, entry_any), 'structured_content', None)
-                        if isinstance(structured, dict):
-                            candidate = cast(dict[str, Any], structured).get('context_id')
-                        if candidate is None and isinstance(entry_any, dict):
-                            entry_typed = cast(dict[str, Any], entry_any)
-                            nested: Any = entry_typed.get('structured_content')
-                            if isinstance(nested, dict):
-                                candidate = cast(dict[str, Any], nested).get('context_id')
-                            if candidate is None:
-                                candidate = entry_typed.get('context_id')
-                        if candidate is None:
-                            continue
-                        try:
-                            chunk_ids.append(int(candidate))
-                        except (TypeError, ValueError):
-                            continue
+                    chunk_ids = result.get('chunk_ids', [])
                     if chunk_ids:
-                        # Persist FIRST so the sidecar / observed-IDs files are durable
-                        # on disk before the orchestrator can see additionalContext
-                        # referencing these IDs. Closes the persist/emit race window
-                        # at source: downstream readers (validate_agent_invocation,
-                        # orchestrator_sequencing_enforcement) can rely on the files
-                        # being present whenever the upstream prompt mentions an ID.
-                        session_id_value = str(input_data.get('session_id', '')) or 'unknown'
-                        _persist_user_prompt_context_id(session_id_value, chunk_ids, str(prompt))
-
                         hook_output: dict[str, Any] = {
                             'hookSpecificOutput': {
                                 'hookEventName': 'UserPromptSubmit',
@@ -1912,19 +1739,10 @@ def main() -> None:
             else:
                 log_always('SUCCESS: Context stored successfully')
 
-                # Output context_id via additionalContext for orchestrator reference.
-                # Persist FIRST so the sidecar / observed-IDs files are durable on disk
-                # before the orchestrator can see additionalContext referencing the ID.
+                # Output context_id via additionalContext for orchestrator reference
                 if config.get('output_context_id', True):
                     context_id = result.get('context_id')
                     if context_id is not None:
-                        session_id_value = str(input_data.get('session_id', '')) or 'unknown'
-                        try:
-                            single_id = int(context_id)
-                            _persist_user_prompt_context_id(session_id_value, [single_id], str(prompt))
-                        except (TypeError, ValueError):
-                            pass
-
                         hook_output = {
                             'hookSpecificOutput': {
                                 'hookEventName': 'UserPromptSubmit',

agents/claude-code/rules/context-server-integration.md

@@ -4,14 +4,9 @@
 
 When MCP Context Server tools are available (any `mcp__context-server__*` tool in your tools list), you MUST follow this rule. If no context-server tools are present, this rule is inactive.
 
-## Mandatory Skill Delegation
+## Core Operating Principles
 
-For ALL context-server operations (retrieval, search, storage, metadata, update/revision, scoped retrieval, references navigation, continuity, pre-compaction patterns), you MUST follow these skills as the authoritative source of truth:
-
-- **Retrieval:** `context-retrieval-protocol` skill -- thread ID acquisition, project name derivation, retrieval sequences, hybrid/semantic/FTS search, scoped retrieval (`context_scope`), references navigation, revision context detection, worktree-aware queries, and continuity patterns.
-- **Preservation:** `context-preservation-protocol` skill -- storage patterns, metadata schema (including the "task subject vs execution tools" distinction for the `technologies` field), `store_context` vs `update_context` strategy, handoff reports, and continuity patterns.
-
-If these skills are already loaded in your context (via your agent frontmatter `skills:` field or a slash-command invocation), treat them as active. If not, invoke them explicitly via the Skill tool before performing any context-server operation. **Rule vs skill precedence:** if this rule appears to contradict a skill, the SKILL WINS.
+For ALL context-server operations (retrieval, search, storage, metadata, update/revision, scoped retrieval, references navigation, continuity, pre-compaction patterns), apply these principles directly. Where your environment provides skills, tutorials, or other operational guidance, treat that guidance as the practical embodiment of these principles; this rule supplies the invariants those guides must respect.
 
 ## Environment-Specific Facts
 
@@ -20,35 +15,36 @@ If these skills are already loaded in your context (via your agent frontmatter `
 
 ## User Message Authority
 
-User messages are the authoritative source of truth and override orchestrator summaries, agent reports, and your own memory when conflicts arise. User messages are IMMUTABLE -- never update, rewrite, or delete them, even when they contain errors. For discrepancy-handling details, see the retrieval skill's orchestrator-verification section.
+User messages are the authoritative source of truth and override orchestrator summaries, agent reports, and your own memory when conflicts arise. User messages are IMMUTABLE -- never update, rewrite, or delete them, even when they contain errors. When you detect a discrepancy between an orchestrator's task and the user's stated requirements (retrieved verbatim from the context server), the user-message wording wins; the orchestrator's framing is corrected, not the user's words.
 
-## User Message Relay Protocol (ID-First)
+## User Message Relay Protocol
 
-When launching subagents (via the Task or Agent tool) whose work depends on the user request, you MUST relay the user message using one of two modes, chosen by a deterministic predicate on `context_id` availability. Message SIZE is IRRELEVANT to mode selection.
+When launching subagents (via the Task or Agent tool) whose work depends on the user request, you MUST pass the user message in one of two modes:
 
-- **Default Mode -- REFERENCE (context_id only):** This is the ALWAYS-PREFERRED mode regardless of message size. Use it whenever the UserPromptSubmit hook has emitted a `context_id` for the current user message. The Reference Block contains EXACTLY this one line and nothing else (no retrieval instructions, no CRITICAL reminders, no size annotations, no format descriptors):
+- **Mode 1 -- INLINE (default):** For moderate messages (guidance: under approximately 2000 tokens / 40 lines), include the full verbatim text under a `USER REQUEST:` marker:
 
   ```text
-  USER REQUEST CONTEXT ID: [context_id from hook]
+  USER REQUEST: [verbatim user message]
   ```
 
-- **Fallback Mode -- INLINE (verbatim text):** Use ONLY when the `context_id` is unavailable -- the UserPromptSubmit hook did not emit one (hook failure or upstream error), or the context-server is unreachable at message-store time. Include the full verbatim text under a `USER REQUEST:` marker:
+- **Mode 2 -- REFERENCE (large messages):** Use a reference block with explicit retrieval instructions, passing the `context_id` emitted by the hook:
 
   ```text
-  USER REQUEST: [verbatim user message text]
+  USER REQUEST (large message -- retrieve from context-server):
+  Context ID: [context_id from hook additionalContext]
+  Retrieve the FULL user message using: get_context_by_ids([<context_id>])
+  CRITICAL: You MUST retrieve and read the COMPLETE user message before starting work.
   ```
 
-**Prohibitions (both modes):** MUST NOT summarize, paraphrase, condense, compress, or select "relevant" portions; MUST NOT extract quotes, evidence, or excerpts; MUST NOT describe intent or problem in your own words; MUST NOT add domain, technology, or problem qualifiers. Relay the complete message (REFERENCE) or its complete verbatim text (INLINE). When a subagent receives a Reference Block, it resolves the pointer per the retrieval skill's Pattern 6 (User Request Resolution) before starting work.
-
-**Image Path Relay (extension to BOTH modes):** Images attached via the terminal are NOT stored in the context-server; subagents can only analyze them by reading the absolute paths directly with the `Read` tool. Whenever the task involves visual analysis, the orchestrator MUST forward image paths verbatim: in Fallback (INLINE) mode the paths flow naturally with the verbatim text; in Default (REFERENCE) mode the orchestrator MUST append an explicit `IMAGE PATHS` block after the Reference Block, because image paths cannot be retrieved from the context-server. The orchestrator MUST NOT summarize, describe, interpret, or redact image contents or paths.
+**Prohibitions (both modes):** MUST NOT summarize, paraphrase, condense, compress, or select "relevant" portions; MUST NOT extract quotes, evidence, or excerpts; MUST NOT describe intent or problem in your own words; MUST NOT add domain, technology, or problem qualifiers. Pass the complete message. **Fallback:** if the context server is unavailable, use Mode 1 INLINE regardless of size. When a subagent receives a Mode 2 reference block, it MUST resolve the pointer FIRST -- retrieve the full verbatim user message via `get_context_by_ids([<context_id>])`, read it in full, and only then begin work. Acting on the reference pointer without retrieving the underlying message is a PROTOCOL VIOLATION.
 
 ## Subagent Context Requirements
 
 When launching subagents via the Task or Agent tool, the task description MUST include:
 
 1. **Thread ID** -- enforced by a PreToolUse blocker
 2. **Timezone / date context** -- enforced by a PreToolUse blocker
-3. **User original request** -- per the Relay Protocol above (Default REFERENCE pointer, or INLINE fallback when no `context_id`)
+3. **User original request** -- per the Relay Protocol above (Mode 1 or Mode 2)
 4. **Relevant context IDs** -- so the subagent can retrieve prior work via `get_context_by_ids`
 
 Items 1 and 2 are hook-enforced: if missing, the tool call is blocked with guidance via stderr -- revise the task description and retry. Items 3 and 4 are your responsibility.
@@ -62,4 +58,4 @@ Before context compaction, preserve (priority-ordered):
 - **Current task state** -- what is active and what remains
 - **User decisions** -- explicit choices made during this session
 
-Do NOT attempt to preserve full content already stored in the context server -- use context IDs for retrieval after compaction. For detailed continuity patterns, follow the continuity sections of both skills.
+Do NOT attempt to preserve full content already stored in the context server -- use context IDs for retrieval after compaction. After any context window reset or compaction event, re-retrieve the highest-priority items above via `get_context_by_ids` before continuing work.