# KB Retrieval Agent Scope Semantic-Drift Review Package

Prepared for the final #t895 / PR #1727 batch review after the #t902 cleanup pass.

## Commit map

- #t896 `273322f79` — added MeshX agent KB permission summaries and the agent-accessible KB listing surface.
- #t897 `bdc3f6065` — moved KB retrieval enforcement into MeshX agent principal scope.
- #t898 `9a050d0ea` — lists hidden KB channel thread history instead of relying on retrieval thread records.
- #t899 `0073f8230` — removed the AgentTeam KB retrieval thread API wrapper.
- #t900 `6f99360e1` — refactored the agent KB proxy to generic agent/thread attestation.
- #t901 `5f52f9aee` and `ba52dd4ef` — updated the web/desktop UX and removed the legacy agent-scoped KB endpoint surface.
- #t902 `56ddff0b0` plus follow-up cleanup commits — moved the attestation gateway into the generic forwarder boundary, then removed AgentTeam-side parsing/attestation of KB query and selected-KB IDs in favor of generic hidden agent-thread/session transport.

## Semantics checklist

- AgentTeam `/api/v1/kb/*` remains a generic KB gateway: no retrieval thread special-case is required for KB authorization.
- AgentTeam agent-thread calls use generic agent/thread/session attestation and forward raw operation requests; AgentTeam does not parse query/knowledge-base IDs for attestation, rewrite KB request bodies, or switch behavior by KB operation.
- MeshX product endpoints stay in the MeshX KB retrieval namespace; `agent-thread` terminology is limited to AgentTeam attestation/header/context code.
- MeshX owns agent principal KB permissions and retrieval scope enforcement.
- Web selects an agent, displays that agent's accessible KBs, writes generic `agentThreadSession` transport metadata for AgentTeam, and keeps KB query/KB ids only in KB-owned metadata and MeshX request bodies.
- Unauthorized selected/filter KB ids are rejected by MeshX agent-scope checks; omission defaults to the agent-accessible set.
- Hidden agent-thread/session channel thread history remains the retrieval history source; its DB subsystem value is the legacy hidden carrier value, not an AgentTeam authorization boundary.

## Focused regression evidence

- AgentTeam core: focused `go test` commands cover `./internal/api/agent`, `./internal/forwarder`, `./internal/store/message`, and the agent-thread/session store integration test.
- MeshX: `(cd meshx && go test ./internal/api/kb ./internal/service ./internal/store/kb ./internal/database ./internal/server)` passes, including agent-attested search and unauthorized KB filter rejection coverage.
- Desktop: `(cd desktop && go test ./internal/channel/agentteam)` passes, covering the generic agent-thread upstream MCP boundary.
- Web: `(cd web && npx tsx --test src/agentteam/api.test.ts src/agentteam/pages/WorkspaceShell.kb.test.ts src/agentteam/workspace/knowledge-base/KnowledgeBasesPanel.test.ts)` passes after refreshing local `node_modules`; `(cd web && npm run typecheck)` also passes.
- Hygiene: `git diff --check` passes.

## Forbidden-remnant sweeps

- No old retrieval-session route token hits.
- No old agent-thread knowledge endpoint hits.
- No old server forwarder file path remains.
- No old snake_case agent-thread forwarder symbol/path hits remain.
- No old facade/type-name AgentTeam DTO remnants remain.
- MeshX agent/knowledge permission model hits are product-domain permission models/tests and are intentional terminology.
- `selectedKnowledgeBase` hits are normal KB-detail UI state, not selected-KB authorization or AgentTeam-side request rewriting.
- `retrieval thread` wording remains only for the hidden thread conversation/history UX and related tests/docs.
- Regex rewrite/knowledge hits are unrelated promptcompiler fixture text about workspace memory, not KB request/body rewrite helpers.

## Intentional remaining terminology / risks

- User-facing copy and KB web APIs may still say “retrieval thread” for the hidden thread conversation experience. That is descriptive UI/product language; AgentTeam core attestation no longer carries query or selected-KB IDs.
- Knowledge MCP tool descriptions describe KB ids as filters presented to the model. MeshX remains the enforcement point.
- Local Web verification required `npm ci` because the isolated worktree's `node_modules` was incomplete; this did not change tracked dependency files.