Skip to content

✨ knowledge: per-entry visibility (audience) and repo auto-scope #17077

Closed as not planned

Description

@clubanderson

Second half of @gregoryhunt's knowledge-scoping investigation from the 2026-11-05 community meeting (the first half, drafts reaching their author's agent, is tracked separately). Design issue: file anchors below, no PR yet.

Gaps

Today the only access control on knowledge is knowledge.agent_scopes (src/pkg/config/knowledge_config.go, knowledge.AgentScope in src/pkg/knowledge/toc.go): an allow-list per agent over layers / repos / types / tags / include_states. Two things cannot be expressed:

  1. Who may read an entry, stated on the entry. There is no notion of audience on the fact itself. An operator cannot write "this entry is for the maintainer's agents only, never for a contributor-container agent" or "only the claude family may see this" without inventing a tag and remembering to mirror it in every agent's tags: allow-list — and tag allow-lists are any-match, so a single shared tag re-admits the entry. The public MCP (src/pkg/dashboard/mcp_knowledge.go, knowledge.public.tags) and the contributor-container path (🔒 security(contribute): container mode stages the contributor's entire ~/.claude (all transcripts, prompt history, paste cache, memory, CLAUDE.md) into the agent sandbox — only the credential file is needed #7836 family) have the same problem: visibility is decided by the reader's config, not by the entry.
  2. Repo auto-scope. agent_scopes.repos hides repo:<name>-tagged entries from an agent, but a kick is not filtered by the repos of the issues it is about: primeKnowledgeStats (src/pkg/scheduler/kick_priming.go) only passes keywords, so an entry about repo X is offered to a kick for repo Y whenever the keywords match (documented as such in src/docs/agent-knowledge-and-memory.md, "By the work, not the repo"). ✨ knowledge: scope block (paths, labels, lanes) on entries and a kick-context filter in the Primer #17045 adds scope.paths/labels/lanes but not repos.

Proposal

audience: frontmatter

audience: [maintainers]                 # default when absent: maintainers + their agents
audience: [contributors]                # also readable from contributor containers
audience: [agents: [developer, scanner]]  # inline map form, or audience_agents: [developer, scanner]
audience: [families: [claude, codex]]     # or audience_families: [claude, codex]
audience: [public]                      # eligible for the public MCP (still gated by knowledge.public.tags)

Flat keys (audience, audience_agents, audience_families) are preferred because the frontmatter parser in filestore.go is line-oriented and the scope: block in #17045 already shows the cost of nesting.

Semantics — a reader is a tuple (role, agent, family); an entry is visible when every declared dimension admits the reader (AND across dimensions, OR within a list):

  • role: maintainers (hive-owned agents and operator reads), contributors (contributor-container agents), public (unauthenticated MCP). Absent → maintainers. contributors implies maintainers; public implies both.
  • agents: base agent names (Config.BaseAgentName); absent → any agent.
  • families: CLI family of the agent (claude, codex, gemini, bob, …, from the agent's cli config); absent → any.

Enforcement points

  • FactAudience type + Admits(reader) in a new src/pkg/knowledge/audience.go; parse in parseObsidianFileDetailed (filestore.go), carried on Fact.
  • Kick path: Primer.PrimeForKick (✨ knowledge: scope block (paths, labels, lanes) on entries and a kick-context filter in the Primer #17045) gets the reader on KickContext (Agent, Family, Role: maintainers); expandWithGraph gates related facts the same way.
  • Pull path: handleKnowledgeTOC / handleKnowledgeEntry / handleKnowledgeEffective (src/pkg/dashboard/api_knowledge_toc.go) derive the reader from agent= + the caller's dashboard role; the effective view reports ExcludedAudience as a new exclusion reason alongside lifecycle|layer|repo|type|tag (TOCScope.ExclusionReason).
  • Public MCP (mcp_knowledge.go): knowledge_toc/knowledge_get require public in the audience in addition to the existing knowledge.public.tags gate.
  • Contributor containers: the kick built for a contributor-container agent sets Role: contributors.

repo auto-scope

  • Extend ✨ knowledge: scope block (paths, labels, lanes) on entries and a kick-context filter in the Primer #17045's FactScope with Repos []string; an entry with scope.repos is admitted only for a kick whose issues are on one of those repos (github.Issue.Repo, passed via KickContext.Repos from primeKnowledgeStats). repo:<name> tags keep their current meaning for agent_scopes.repos.
  • Entries indexed from a repo's src/docs/knowledge/ (the project-knowledge directory of src/docs/knowledge-entries.md) inherit scope.repos: [<org>/<repo>] and a repo:<org>/<repo> tag when they declare neither, so a repo's own facts are never offered to another repo's kick.

Non-goals

  • No change to agent_scopes semantics; the agent allow-list still applies first, the entry's audience can only narrow.
  • Entries without audience: behave exactly as today for maintainers; the only behaviour change for unannotated entries is that public MCP reads additionally require an explicit public audience — to be decided (could default to today's tag-only gate behind a knowledge.public.require_audience flag).

Tests to write

Table-driven on FactAudience.Admits (role implication, agents, families, AND across dimensions); primer test that a contributors entry reaches a contributor kick and a maintainers entry does not; TOC effective test showing audience as the exclusion reason; kick test that a scope.repos: [org/x] entry is dropped for an org/y issue and kept for org/x.

Activity

  1. added
    help wantedDenotes an issue that needs help from a contributor. Must meet "help wanted" guidelines.
    on Nov 7, 2026
  2. clubanderson commented on Nov 7, 2026

    @clubanderson
    MemberAuthor

    Parking this: per-entry audience/RBAC is premature while hives are single-owner. Revisit when a hive has multiple humans with different rights (team-collaboration gap). Draft-visibility piece continues in #17079.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    help wantedDenotes an issue that needs help from a contributor. Must meet "help wanted" guidelines.

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions