Skip to content
CommandChain CommandChain CommandChain Docs

Knowledge in runs

An agent working in a repository can only see the repository. Plenty of what it needs to get a task right is somewhere else: a meeting where the approach was decided, a document describing your product, a workspace page with the conventions.

Knowledge search closes that gap. When a run has it, the coding agent gets one extra tool it can call mid-run, without leaving the sandbox.

What the agent gets

Section titled “What the agent gets”

Exactly one tool, called knowledge_search. It takes a query and returns matching passages from your workspace knowledge, with enough context to act on and a pointer back to the source.

It is read-only by construction. The tool surface has one entry, that entry is a search, and there is no second tool to write, delete, or list anything. An agent that wants to change your knowledge cannot; it can only ask what is in it.

Under the sandbox, the tool runs as a small process the runner starts inside the same boundary as the agent, which forwards each search to your workspace over the network. It never gets a filesystem path into your knowledge store.

What it searches

Section titled “What it searches”

Whatever your workspace has ingested, which typically includes:

  • Meeting summaries, so a decision made in conversation is available to the agent implementing it.
  • Workspace documents and pages your team has written.
  • Company profile material, so the agent works from your product’s actual truth.
  • Repository content that has been indexed.

See knowledge for what it is and how material gets into it.

When a run has it

Section titled “When a run has it”

Knowledge search is granted per run by the control plane, not switched on by the machine. The runner reads the capability the run was dispatched with and stages the tool only when it is present. Absent, false, or unrecognised all mean the same thing: no tool.

That has two consequences worth knowing:

  • An older runner against a newer workspace simply does not get the tool. It does not fail the run, and it does not guess.
  • You cannot enable it on the runner. There is no flag on the machine. If a run should have knowledge and does not, the answer is in your workspace configuration, not on the host.

How the credential is handled

Section titled “How the credential is handled”

The tool authenticates with the same attempt-scoped token the runner already holds for that attempt. That token:

  • is written into a 0600 file in a per-attempt directory outside the git workspace, so it can never be committed;
  • is never passed on a command line, where any process on the machine could read it;
  • is never written to a log, because it is registered with the log scrubber before it exists on disk;
  • dies with the attempt, along with the rest of the attempt’s synthetic home.

This is the same discipline as every other secret a run touches. See the security model.

What to expect in a run

Section titled “What to expect in a run”

Searches show up in the run’s timeline like any other tool call, so you can see what the agent looked for and what came back. If an agent is producing work that contradicts a decision your team already made, the run timeline is the place to check whether it searched at all.

Next steps

Section titled “Next steps”