switchroom 0.19.34 → 0.19.36

package/vendor/hindsight-memory/scripts/lib/secret_redaction_vectors.json

@@ -0,0 +1,397 @@
+{
+  "_purpose": "Shared behaviour vectors for the secret redactor. The TypeScript engine (telegram-plugin/secret-detect/redact.ts) and the Python engine (vendor/hindsight-memory/scripts/lib/secret_redact.py) must produce IDENTICAL output for every case here. Asserted by telegram-plugin/tests/secret-detect-write-path.test.ts and vendor/hindsight-memory/scripts/tests/test_secret_redact.py.",
+  "_secrets_note": "Every value below is synthetic. Token-shaped strings are assembled from repeated filler so no real credential is committed and GitHub Push Protection has nothing to match.",
+  "vectors": [
+    {
+      "name": "postgres connection string password is masked",
+      "input": "connect with postgres://appuser:HunterTwo99@db.internal:5432/prod",
+      "expected": "connect with postgres://appuser:[REDACTED:db_uri_password]@db.internal:5432/prod"
+    },
+    {
+      "name": "mysql connection string password is masked",
+      "input": "mysql://root:t0psecretpw@127.0.0.1:3306/app",
+      "expected": "mysql://root:[REDACTED:db_uri_password]@127.0.0.1:3306/app"
+    },
+    {
+      "name": "mongodb+srv connection string password is masked",
+      "input": "MONGO=mongodb+srv://svc:aB3dEf9hJ2@cluster0.example.net/db",
+      "expected": "MONGO=mongodb+srv://svc:[REDACTED:db_uri_password]@cluster0.example.net/db"
+    },
+    {
+      "name": "redis connection string password is masked",
+      "input": "redis://default:cachePass42@redis.internal:6379/0",
+      "expected": "redis://default:[REDACTED:db_uri_password]@redis.internal:6379/0"
+    },
+    {
+      "name": "postgres URI without credentials is untouched",
+      "input": "postgres://db.internal:5432/prod is the read replica",
+      "expected": "postgres://db.internal:5432/prod is the read replica"
+    },
+    {
+      "name": "already-masked connection string is stable",
+      "input": "postgres://appuser:[REDACTED:db_uri_password]@db.internal:5432/prod",
+      "expected": "postgres://appuser:[REDACTED:db_uri_password]@db.internal:5432/prod"
+    },
+    {
+      "name": "human-memorable password after a colon is masked",
+      "input": "password: FluffyBarnaby1998",
+      "expected": "password: [REDACTED:memorable_password]"
+    },
+    {
+      "name": "human-memorable password in prose is masked",
+      "input": "the wifi password is MangoTreeHouse77 if you need it",
+      "expected": "the wifi password is [REDACTED:memorable_password] if you need it"
+    },
+    {
+      "name": "prefixed password identifier is masked",
+      "input": "db_password=Rutherford2024x",
+      "expected": "db_password=[REDACTED:memorable_password]"
+    },
+    {
+      "name": "passphrase label is covered",
+      "input": "passphrase: CorrectHorse9Battery",
+      "expected": "passphrase: [REDACTED:memorable_password]"
+    },
+    {
+      "name": "single-class prose after 'password is' is NOT masked",
+      "input": "the password is rotated quarterly by the platform team",
+      "expected": "the password is rotated quarterly by the platform team"
+    },
+    {
+      "name": "password policy prose is NOT masked",
+      "input": "The password policy requires rotation every 90 days.",
+      "expected": "The password policy requires rotation every 90 days."
+    },
+    {
+      "name": "shell variable reference is NOT masked",
+      "input": "password: ${DB_PASSWORD}",
+      "expected": "password: ${DB_PASSWORD}"
+    },
+    {
+      "name": "angle-bracket placeholder is NOT masked",
+      "input": "password=<your-password-here>",
+      "expected": "password=<your-password-here>"
+    },
+    {
+      "name": "vault reference is NOT masked",
+      "input": "password: vault:postgres/app_password",
+      "expected": "password: vault:postgres/app_password"
+    },
+    {
+      "name": "already-masked memorable password is stable",
+      "input": "password: [REDACTED:memorable_password]",
+      "expected": "password: [REDACTED:memorable_password]"
+    },
+    {
+      "name": "https url credentials are stripped by the url pass",
+      "input": "see https://alice:s3cretpw@api.example.com/v1/things",
+      "expected": "see https://***@api.example.com/v1/things"
+    },
+    {
+      "name": "sensitive query param is masked",
+      "input": "hit https://api.example.com/v1?api_key=abcdef123456&trace=42",
+      "expected": "hit https://api.example.com/v1?api_key=***&trace=42"
+    },
+    {
+      "name": "plain url is untouched",
+      "input": "docs at https://example.com/guide?page=2",
+      "expected": "docs at https://example.com/guide?page=2"
+    },
+    {
+      "name": "ordinary prose is untouched",
+      "input": "I told him the answer was probably Gandalf the Grey.",
+      "expected": "I told him the answer was probably Gandalf the Grey."
+    },
+    {
+      "name": "empty string passes through",
+      "input": "",
+      "expected": ""
+    },
+    {
+      "name": "multi-secret line masks every hit",
+      "input": "db postgres://u:PineappleRoof8@h/d and wifi password: SparrowKettle31",
+      "expected": "db postgres://u:[REDACTED:db_uri_password]@h/d and wifi password: [REDACTED:memorable_password]"
+    },
+    {
+      "name": "anthropic api key is masked",
+      "input": "the key is \u0073k-ant-api03-AAAABBBBCCCCDDDDEEEEFFFFGGGGHHHHIIIIJJJJ ok",
+      "expected": "the key is [REDACTED:anthropic_api_key] ok"
+    },
+    {
+      "name": "anthropic api key adjacent to CJK text is masked",
+      "input": "トークンは\u0073k-ant-api03-AAAABBBBCCCCDDDDEEEEFFFFGGGGHHHHIIIIJJJJです",
+      "expected": "トークンは[REDACTED:anthropic_api_key]です"
+    },
+    {
+      "name": "openai style key is masked",
+      "input": "OPENAI sk-AAAABBBBCCCCDDDDEEEEFFFFGGGGHHHHIIIIJJJJKKKK",
+      "expected": "OPENAI [REDACTED:openai_api_key]"
+    },
+    {
+      "name": "github pat is masked next to Cyrillic text",
+      "input": "ключ \u0067hp_AAAABBBBCCCCDDDDEEEEFFFFGGGGHHHHIIIIк",
+      "expected": "ключ [REDACTED:github_pat_classic]к"
+    },
+    {
+      "name": "aws access key id is masked",
+      "input": "\u0041KIAAAAABBBBCCCCDDDD is the id",
+      "expected": "[REDACTED:aws_access_key] is the id"
+    },
+    {
+      "name": "google api key is masked",
+      "input": "\u0041IzaAAAABBBBCCCCDDDDEEEEFFFFGGGGHHHHIII",
+      "expected": "[REDACTED:google_api_key]"
+    },
+    {
+      "name": "slack bot token is masked",
+      "input": "\u0078oxb-111111111111-AAAABBBBCCCCDDDDEEEEFFFF",
+      "expected": "[REDACTED:slack_token]"
+    },
+    {
+      "name": "jwt is masked next to accented latin text",
+      "input": "jetón eyJAAAABBBBCCCC.DDDDEEEEFFFF.GGGGHHHHIIIIé",
+      "expected": "jetón [REDACTED:jwt]é"
+    },
+    {
+      "name": "telegram bot token is masked",
+      "input": "bot1234567:AAAABBBBCCCCDDDDEEEEFFFFGGGGHH",
+      "expected": "bot[REDACTED:telegram_bot_token_prefixed]"
+    },
+    {
+      "name": "sanctum style token is masked",
+      "input": "17|AAAABBBBCCCCDDDDEEEEFFFFGGGGHHHHIIIIJJJJ",
+      "expected": "[REDACTED:laravel_sanctum_token]"
+    },
+    {
+      "name": "uppercase env assignment is masked",
+      "input": "API_TOKEN=zQ7xVb2nKd9wRt4y",
+      "expected": "API_TOKEN=[REDACTED]"
+    },
+    {
+      "name": "uppercase env assignment adjacent to Thai text is masked",
+      "input": "กุญ API_TOKEN=zQ7xVb2nKd9wRt4yก",
+      "expected": "กุญ API_TOKEN=[REDACTED]"
+    },
+    {
+      "name": "authorization bearer header is masked",
+      "input": "Authorization: Bearer AAAABBBBCCCCDDDDEEEEFFFF",
+      "expected": "Authorization: Bearer [REDACTED:bearer_auth_header]"
+    },
+    {
+      "name": "lowercase authorization bearer header is masked",
+      "input": "authorization: bearer AAAABBBBCCCCDDDDEEEEFFFF",
+      "expected": "authorization: bearer [REDACTED:bearer_auth_header]"
+    },
+    {
+      "name": "authorization basic header is masked",
+      "input": "Authorization: Basic YWxpY2U6c3VwZXJzZWNyZXQ=",
+      "expected": "Authorization: Basic [REDACTED:basic_auth_header]"
+    },
+    {
+      "name": "json secret field is masked",
+      "input": "{\"apiKey\": \"zQ7xVb2nKd9wRt4y\"}",
+      "expected": "{\"apiKey\": \"[REDACTED:json_secret_field]\"}"
+    },
+    {
+      "name": "cli flag value is masked",
+      "input": "run --api-key zQ7xVb2nKd9wRt4y",
+      "expected": "run --api-key [REDACTED:cli_flag]"
+    },
+    {
+      "name": "no-break-space (U+00A0) separator after the key still masks",
+      "input": "API_TOKEN: zQ7xVb2nKd9wRt4y",
+      "expected": "API_TOKEN: [REDACTED]"
+    },
+    {
+      "name": "pem private key block is masked",
+      "input": "-----BEGIN RSA PRIVATE KEY-----\nAAAABBBBCCCC\n-----END RSA PRIVATE KEY-----",
+      "expected": "[REDACTED:pem_private_key]"
+    },
+    {
+      "name": "sentence-final 'required' after 'password is' is NOT masked",
+      "input": "The password is required.",
+      "expected": "The password is required."
+    },
+    {
+      "name": "sentence-final 'incorrect' after 'password is' is NOT masked",
+      "input": "The password is incorrect.",
+      "expected": "The password is incorrect."
+    },
+    {
+      "name": "sentence-final 'unchanged' after 'password is' is NOT masked",
+      "input": "Ken confirmed the password is unchanged.",
+      "expected": "Ken confirmed the password is unchanged."
+    },
+    {
+      "name": "comma-terminated prose after a password label is NOT masked",
+      "input": "password: required, minimum twelve characters, mixed case",
+      "expected": "password: required, minimum twelve characters, mixed case"
+    },
+    {
+      "name": "uppercase env vault reference is NOT masked",
+      "input": "POSTGRES_PASSWORD: vault:pg/password",
+      "expected": "POSTGRES_PASSWORD: vault:pg/password"
+    },
+    {
+      "name": "lowercase env vault reference is NOT masked",
+      "input": "postgres_password: vault:pg/password",
+      "expected": "postgres_password: vault:pg/password"
+    },
+    {
+      "name": "uppercase env shell placeholder is NOT masked",
+      "input": "PASSWORD: ${DB_PASSWORD}",
+      "expected": "PASSWORD: ${DB_PASSWORD}"
+    },
+    {
+      "name": "uppercase env angle placeholder is NOT masked",
+      "input": "JWT_SECRET=<generate-with-openssl-rand>",
+      "expected": "JWT_SECRET=<generate-with-openssl-rand>"
+    },
+    {
+      "name": "api key vault reference is NOT masked",
+      "input": "ANTHROPIC_API_KEY: vault:anthropic/api_key",
+      "expected": "ANTHROPIC_API_KEY: vault:anthropic/api_key"
+    },
+    {
+      "name": "process.env reference is NOT masked",
+      "input": "const API_KEY = process.env.ANTHROPIC_API_KEY",
+      "expected": "const API_KEY = process.env.ANTHROPIC_API_KEY"
+    },
+    {
+      "name": "cli flag placeholder in help text is NOT masked",
+      "input": "--token <value>   the API token",
+      "expected": "--token <value>   the API token"
+    },
+    {
+      "name": "changeme placeholder is NOT masked",
+      "input": "DB_PASSWORD=changeme-in-production",
+      "expected": "DB_PASSWORD=changeme-in-production"
+    },
+    {
+      "name": "json doc string is NOT masked",
+      "input": "{\"token\": \"the bearer token to use\"}",
+      "expected": "{\"token\": \"the bearer token to use\"}"
+    },
+    {
+      "name": "ssh public key is NOT masked",
+      "input": "ssh-rsa AAAAB3NzaAAAABBBBCCCCDDDDEEEEFFFFGGGGHHHH deploy@host",
+      "expected": "ssh-rsa AAAAB3NzaAAAABBBBCCCCDDDDEEEEFFFFGGGGHHHH deploy@host"
+    },
+    {
+      "name": "dsn password containing an unencoded at-sign is fully masked",
+      "input": "postgres://appuser:p@ssW0rd123@db.internal:5432/prod",
+      "expected": "postgres://appuser:[REDACTED:db_uri_password]@db.internal:5432/prod"
+    },
+    {
+      "name": "memorable password at the end of a sentence is masked",
+      "input": "The wifi password is MangoTreeHouse77.",
+      "expected": "The wifi password is [REDACTED:memorable_password]"
+    },
+    {
+      "name": "inert angle wrapper does NOT smuggle a value past env_key_value",
+      "input": "POSTGRES_PASSWORD: <a8f3c1d2e4b50f6a9c7d3e81b2f45a6cd90e17bb>",
+      "expected": "POSTGRES_PASSWORD: [REDACTED]"
+    },
+    {
+      "name": "inert angle wrapper does NOT smuggle a value past json_secret_field",
+      "input": "{\"token\": \"<tok_Zq7xVb2nKd9wRt4y>\"}",
+      "expected": "{\"token\": \"[REDACTED:json_secret_field]\"}"
+    },
+    {
+      "name": "inert angle wrapper does NOT smuggle a value past cli_flag",
+      "input": "--token <a8f3c1d2e4b50f6a9c7d3e81b2f45a6cd90e17bb>",
+      "expected": "--token [REDACTED:cli_flag]"
+    },
+    {
+      "name": "handlebars wrapper does NOT smuggle a value through",
+      "input": "POSTGRES_PASSWORD: {{a8f3c1d2e4b50f6a9c7d3e81b2f45a6cd90e17bb}}",
+      "expected": "POSTGRES_PASSWORD: [REDACTED]"
+    },
+    {
+      "name": "handlebars wrapper does NOT smuggle a value past cli_flag",
+      "input": "--token {{tok_Zq7xVb2nKd9wRt4y}}",
+      "expected": "--token [REDACTED:cli_flag]"
+    },
+    {
+      "name": "vault: prefix does NOT smuggle a trailing value through",
+      "input": "POSTGRES_PASSWORD: vault:pg/password<a8f3c1d2e4b50f6a9c7d3e81b2f45a6cd90e17bb>",
+      "expected": "POSTGRES_PASSWORD: [REDACTED]"
+    },
+    {
+      "name": "vault: key slot does NOT smuggle a value through",
+      "input": "{\"token\": \"vault:pg/a8f3c1d2e4b50f6a9c7d3e81b2f45a6cd90e17bb\"}",
+      "expected": "{\"token\": \"[REDACTED:json_secret_field]\"}"
+    },
+    {
+      "name": "[REDACTED] marker prefix does NOT smuggle a trailing value through",
+      "input": "POSTGRES_PASSWORD: [REDACTED]a8f3c1d2e4b50f6a9c7d3e81b2f45a6cd90e17bb",
+      "expected": "POSTGRES_PASSWORD: [REDACTED]"
+    },
+    {
+      "name": "[REDACTED:rule] marker prefix does NOT smuggle a trailing value through",
+      "input": "--token [REDACTED:cli_flag]a8f3c1d2e4b50f6a9c7d3e81b2f45a6cd90e17bb",
+      "expected": "--token [REDACTED:cli_flag]"
+    },
+    {
+      "name": "process.env prefix does NOT smuggle a trailing value through",
+      "input": "POSTGRES_PASSWORD: process.env.a8f3c1d2e4b50f6a9c7d3e81b2f45a6cd90e17bb",
+      "expected": "POSTGRES_PASSWORD: [REDACTED]"
+    },
+    {
+      "name": "changeme prefix does NOT smuggle a trailing value through",
+      "input": "{\"token\": \"changeme-a8f3c1d2e4b50f6a9c7d3e81b2f45a6cd90e17bb\"}",
+      "expected": "{\"token\": \"[REDACTED:json_secret_field]\"}"
+    },
+    {
+      "name": "todo prefix does NOT smuggle a trailing value through",
+      "input": "--token todo_a8f3c1d2e4b50f6a9c7d3e81b2f45a6cd90e17bb",
+      "expected": "--token [REDACTED:cli_flag]"
+    },
+    {
+      "name": "handlebars placeholder is NOT masked",
+      "input": "POSTGRES_PASSWORD: {{ db_password }}",
+      "expected": "POSTGRES_PASSWORD: {{ db_password }}"
+    },
+    {
+      "name": "os.environ subscript reference is NOT masked",
+      "input": "API_KEY = os.environ[\"ANTHROPIC_API_KEY\"]",
+      "expected": "API_KEY = os.environ[\"ANTHROPIC_API_KEY\"]"
+    },
+    {
+      "name": "import.meta.env reference is NOT masked",
+      "input": "VITE_API_KEY = import.meta.env.VITE_API_KEY",
+      "expected": "VITE_API_KEY = import.meta.env.VITE_API_KEY"
+    },
+    {
+      "name": "already-masked env value is stable under a second pass",
+      "input": "POSTGRES_PASSWORD: [REDACTED]",
+      "expected": "POSTGRES_PASSWORD: [REDACTED]"
+    },
+    {
+      "name": "already-masked rule-tagged cli flag is stable under a second pass",
+      "input": "--token [REDACTED:cli_flag]",
+      "expected": "--token [REDACTED:cli_flag]"
+    },
+    {
+      "name": "bare todo placeholder is NOT masked",
+      "input": "POSTGRES_PASSWORD: todo-before-launch",
+      "expected": "POSTGRES_PASSWORD: todo-before-launch"
+    },
+    {
+      "name": "single-class 16-char run in an angle wrapper is still masked",
+      "input": "POSTGRES_PASSWORD: <abcdefghijklmnop>",
+      "expected": "POSTGRES_PASSWORD: [REDACTED]"
+    },
+    {
+      "name": "single-class 16-char run in a handlebars wrapper is still masked",
+      "input": "--token {{abcdefghijklmnop}}",
+      "expected": "--token [REDACTED:cli_flag]"
+    },
+    {
+      "name": "a 10-letter word inside a placeholder is NOT masked",
+      "input": "DB_PASSWORD=changeme-in-production",
+      "expected": "DB_PASSWORD=changeme-in-production"
+    }
+  ],
+  "_coverage": "Two classes of vector live here. (a) The IMPERATIVE gates that cannot be generated: the entropy floors, the inert-value list, the memorable-password character-class rule, the connection-URI scanner. (b) The GENERATED pattern table itself -- one vector per credential family, several of them deliberately ADJACENT to non-ASCII text. (b) exists because #3982's review found the two engines forking on Unicode word boundaries (Python re is Unicode-aware, JS RegExp without /u is not) while the byte-compare parity guard stayed green: the SOURCES were identical, the BEHAVIOUR was not, and no vector touched a generated rule. Keep at least one non-ASCII-adjacent vector per new family. Every credential here is synthetic. JSON has no runtime string concatenation, so token-shaped prefixes are broken up with \\uXXXX escapes instead -- json.load / JSON.parse restore the intended bytes, while the file on disk holds no contiguous token literal (CLAUDE.md 'Secrets in tests', scripts/check-no-pii-secrets.mjs, and GitHub Push Protection all require that). The WRAPPER vectors (#3982 review MAJOR 7) pin the other half of the inert gate: a value is skipped only when the WHOLE value is inert, so an inert-looking prefix or bracket pair left around a real credential must NOT suppress the mask."
+}

package/vendor/hindsight-memory/scripts/subagent_retain.py

@@ -3,11 +3,24 @@
 
 Delegated (sub-agent / Task-tool) work is the biggest systematic memory hole:
 the main-session Stop retain only ever reads the parent ``transcript_path``, so
-a worker's hours of process work — the paths it touched, the commands that
-worked, the dead ends — reach memory only as the terse final report the parent
+a worker's hours of reasoning — the constraints it discovered, the structural
+dead ends it ruled out — reach memory only as the terse final report the parent
 transcript captures. This hook closes that hole by retaining a bounded window of
 the *sidechain* transcript when a sub-agent terminates.
 
+Scope (Ken, 2026-07-29): LEARNINGS, not raw transcripts and tools. The window is
+retained on the TEXT-ONLY formatting path (``run_subagent_retain`` forces
+``retainToolCalls = False`` on its config copy), so what reaches memory is the
+sub-agent's own prose — reasoning, findings, final report — and NOT tool_use
+inputs, tool_result bodies, file contents or diffs.
+
+The text-only path cannot format to nothing here: the volume gate already
+requires ``MIN_HUMAN_TURNS`` GENUINE human turns (tool_result-only user messages
+are explicitly not counted, ``count_human_turns``), and every such turn is a
+plain-string user message that ``_extract_text_content`` returns verbatim. So a
+window that clears the gate always carries at least its instruction turns, and
+``build_retain_payload`` never returns None on this path for volume reasons.
+
 Probe result (Claude Code 2.1.215, PR5 Task 0 — recorded in the PR body):
 the ``SubagentStop`` hook input carries BOTH the parent ``transcript_path`` AND
 a first-class ``agent_transcript_path`` pointing straight at the sidechain
@@ -62,8 +75,11 @@ from lib.pacing import inflight_lock
 # stays byte-identical to the main path where it matters (dedup ids, formatting).
 from retain import build_retain_payload, read_transcript
 
-# Retain the last N human turns of the sidechain. Tool-result bodies inside the
-# window are truncated by _extract_message_blocks (content.py) already.
+# Retain the last N human turns of the sidechain. The window is formatted on the
+# TEXT-ONLY path (``retainToolCalls`` is forced False for the sidechain — see
+# ``run_subagent_retain``), so tool_use inputs and tool_result bodies are dropped
+# entirely rather than passed through / truncated. ``_extract_message_blocks`` is
+# still imported here, but only for the volume gate's char count.
 SIDECHAIN_WINDOW_TURNS = 40
 
 # Volume gate floors — SubagentStop fires for every Task, so skip trivial forks.
@@ -256,6 +272,14 @@ def non_tool_result_char_count(messages: list, stop_at: int | None = None) -> in
     the floor even if it emitted a large tool_result, while a real worker's
     commands and decisions count.
 
+    KNOWN MISMATCH (accepted, tracked as a follow-up): this counts ``tool_use``
+    inputs, but those are no longer RETAINED — the sidechain payload is built on
+    the text-only path. So the gate can clear on tool volume that contributes
+    nothing to the stored memory. It cannot produce an EMPTY retain (the
+    ``MIN_HUMAN_TURNS`` floor guarantees prose-bearing user turns — see the
+    module docstring), so this is a precision issue in the gate, not a
+    correctness bug. Tightening it to count only text is a separate change.
+
     ``stop_at`` (review finding 4 — early short-circuit): return as soon as the
     running total reaches this many chars. The gate only needs to know whether
     the floor is CLEARED, not the exact size — so on a large worker transcript
@@ -396,9 +420,32 @@ def run_subagent_retain(hook_input: dict) -> dict:
     # main-session retains: reuse retain.py's ``slice_document_id`` recipe via a
     # composite session key so (a) re-fires of the SAME sub-agent window upsert
     # server-side, and (b) it never collides with the parent's own
-    # ``{session_id}-r...`` documents. Client-side diffing against the parent's
-    # final-report retain is deliberately NOT attempted — overlap is fine, and
-    # hindsight's consolidation dedups (design item 4).
+    # ``{session_id}-r...`` documents.
+    #
+    # Client-side diffing against the parent's final-report retain is still NOT
+    # attempted, but NOT because "hindsight's consolidation dedups" — the
+    # original claim here (design item 4) was FALSE and is the assumption that
+    # licensed the sidechain volume. Verified against the engine source
+    # (upstream image ``ghcr.io/vectorize-io/hindsight``):
+    #   * The only SEMANTIC dedup lives in
+    #     ``hindsight_api/engine/consolidation/consolidator.py`` and is a guard
+    #     on the consolidator's OWN OUTPUT: ``_dedup_adjudicate`` probes a newly
+    #     created/updated ``observation`` against existing ones, passing the
+    #     literal fact-type list ``["observation"]`` to
+    #     ``retrieve_semantic_bm25_combined``.
+    #   * ``world`` and ``experience`` are the raw extracted facts that FEED the
+    #     consolidator (it selects ``fact_type IN ('experience', 'world')`` for
+    #     unconsolidated rows) — they never traverse the observation dedup path.
+    #   * Grepping ``hindsight_api/engine/retain/*.py`` for dedup finds only
+    #     content-hash CHUNK dedup (``chunk_storage.compute_chunk_hash``), i.e.
+    #     byte-identical-chunk skipping. There is no semantic dedup on the
+    #     retain path at all.
+    # So overlap between a sidechain retain and the parent's own retain persists
+    # as extra ``world``/``experience`` rows forever. Volume control has to come
+    # from retaining LESS (see ``retainToolCalls`` below), not from a downstream
+    # dedup that does not exist. Diffing is still skipped here because the
+    # deterministic document_id already makes re-fires of the SAME window upsert,
+    # which is the duplicate class this path can actually create.
     sub_session_id = f"{session_id}-sub-{agent_id}"
 
     # Sidechain tags + a topic-friendly parent link. Reuse the config-driven tag
@@ -407,6 +454,55 @@ def run_subagent_retain(hook_input: dict) -> dict:
     # (recallTagWeights); ``parent_session:<id>`` lets a fresh session pull a
     # worker's process facts by parent.
     sub_config = dict(config)
+
+    # Learnings, not raw transcripts and tools (Ken, 2026-07-29): "I don't want
+    # sub-agents' transcripts but definitely their learnings should be captured
+    # but not raw transcripts and tools."
+    #
+    # With ``retainToolCalls`` on, ``build_retain_payload`` formats the window
+    # via ``_prepare_json_transcript`` → ``_extract_message_blocks``, which emits
+    # every ``tool_use.input`` verbatim (an entire ``Write.content``, a full
+    # ``Edit`` diff, a full ``Bash.command``) plus every ``tool_result`` at up to
+    # 2,000 chars per block.
+    #
+    # The cost mechanism is DOCUMENT FAN-OUT, not one oversized payload: a large
+    # payload is not truncated, it is CAPPED and SPLIT by
+    # ``lib.retain_split.split_retain_content`` at ``retain_content_limit()``
+    # (33,000 chars on the shipped inputs) into ``{base}-p{i}of{n}`` parts
+    # (``client.py`` ~:235). Real sidechain retains have been observed splitting
+    # into 38 parts / 1,022 messages, and every part is separately chunked and
+    # LLM-extracted into ``world``/``experience`` rows. Shrinking the content is
+    # therefore the lever that reduces rows.
+    #
+    # Forcing it OFF for the sidechain path routes the window through
+    # ``_prepare_text_transcript`` → ``_extract_text_content``, keeping assistant
+    # ``text`` blocks and channel-message tool_use text. Measured on real fleet
+    # sidechains: 5.5x smaller over 30 sampled transcripts (2,012,376 → 367,796
+    # chars), and independently 6.4x over the 84 most recent GATE-PASSING ones
+    # (26,278,261 → 4,085,678 chars) — of which 0 formatted to empty and 0 came
+    # out under 500 chars.
+    #
+    # ACCEPTED LOSS — this is not a clean "tool noise only" filter.
+    # ``_extract_text_content`` also drops image blocks, ALL ``tool_result``
+    # content, and sub-agent Task report bodies. So a fact that existed ONLY in
+    # tool output is unrecoverable: if a query returned ``43442`` and the agent
+    # merely replied "checked, it's the backlog", the number is gone. That trade
+    # is deliberate and is what Ken asked for; sub-agent prose was separately
+    # measured to carry durable learnings at essentially the main-session rate
+    # (5.24% vs 6.87%), so the learnings themselves survive.
+    #
+    # Mid-session safety: ``slice_document_id`` derives the BASE id from the
+    # slice's first/last uuids, not from the formatted text, so a re-fire of the
+    # same window still targets the same base id. Note the part SUFFIX embeds the
+    # part total, so a document that used to split into n parts and now splits
+    # into m < n leaves parts m+1..n in place — they are not overwritten and not
+    # duplicated. Historical sidechain rows are untouched by this change; this
+    # fixes INTAKE going forward only.
+    #
+    # Deliberately set on the COPY, not on ``config``: the parent session's own
+    # Stop retain keeps whatever the operator configured.
+    sub_config["retainToolCalls"] = False
+
     base_tags = list(config.get("retainTags") or [])
     extra_tags = ["sidechain", f"parent_session:{session_id}"]
     if agent_type: