Skip to content

Commit 639029d

Browse files
hkaltaiclaude
andauthored
fix(analyst): let analyst read workspace memory and steer it to workspace skills (AltimateAI#1570)
* fix(analyst): let analyst read workspace memory and steer it to workspace skills In a linked project the read-only analyst agent could not call any memory tool, yet the workspace identity section told it to save with `altimate_memory_write` and check `altimate_memory_read`. Its prompt named only the built-in data skills and required every reply to finish through `answer_commit`, which suits data values, not a list of conventions. - analyst may call `altimate_memory_read`, `altimate_memory_refresh` and `altimate_memory_audit`; write, delete and extract stay denied, and data-explorer is unchanged. - The team-memory line names only the memory tools the session's agent can call: a read-only agent is pointed at the read tool and told that builder saves; an agent with neither gets no line. - The analyst prompt loads a matching skill by source precedence, answers questions about team conventions in plain text from skills and memory, and keeps `answer_commit` for data questions. Fixes AltimateAI#1569 Co-Authored-By: Claude Opus 5.5 <[email protected]> * fix(memory): stop the empty memory-read result from naming the write tool analyst can now call `altimate_memory_read` but not `altimate_memory_write`. An empty read told it to "Use altimate_memory_write to save information", steering a read-only agent toward a call it cannot make. The result now only says that no blocks were found. Co-Authored-By: Claude Opus 5.5 <[email protected]> * test(analyst): pin the data-question scope of the answer_commit finalization rule The analyst prompt now limits answer_commit to data questions and lets workspace-knowledge answers finish in plain text; update the pinned finalization assertion and pin the new exclusion sentence. Co-Authored-By: Claude Opus 5.5 <[email protected]> * fix(analyst): match the memory line to the tools the turn actually sends - Share one removal rule (`LLM.removedTools`) between tool resolution and the workspace identity section, so a memory tool switched off on the request, or not registered, is not named in the prompt. - A write-only agent gets the save line without the read-first step. - The analyst prompt checks `altimate_memory_read` only when it has it. - Update the analyst prompt assertion in sql-validation-e2e to the new finalization wording. - Cover all four read/write combinations and one cached outcome rendered for different agents. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> * fix(analyst): state what a memory reload changes, and test the prompt wiring - The analyst permission comment now says a reload syncs like the load every session runs and can drop a local copy of an archived block, rather than calling it read-only. - The prompt comment scopes the memory line to the tools the agent and request keep; tool-free steps withhold every tool the prompt names. - A prompt-loop test checks that the identity section is given the same memory access the tools handed to the model call imply. - Document analyst's memory and workspace-skill access. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> * docs(analyst): list workspace memory and skills in the agents reference Match the agent-modes page, and name the prompt-loop memory tests by what they check. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> * docs(analyst): describe the memory audit log and what a reload changes Add an analyst turn with no memory tools to the prompt-loop test and name the test for what it asserts. Co-Authored-By: Claude Opus 5.5 <[email protected]> * fix(analyst): scope the no-save line to memory blocks and note what a reload removes Analyst keeps training_save for corrections to its own behavior, so the read-only memory line now refers to workspace memory blocks only and no longer names one specific agent. The refresh tool description says it can remove local copies of archived blocks. Co-Authored-By: Claude Opus 5.5 <[email protected]> --------- Co-authored-by: Claude Opus 5.5 <[email protected]>
1 parent eb2b737 commit 639029d

17 files changed

Lines changed: 224 additions & 21 deletions

File tree

‎docs/docs/configure/agents.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,7 @@ The agent for asking questions about your data. Truly read-only mode for safe da
2828
- **Bash**: Safe commands auto-allowed (`ls`, `grep`, `cat`, `head`, `tail`, `find`, `wc`). dbt read commands allowed (`dbt list`, `dbt ls`, `dbt debug`). Everything else denied.
2929
- **Web**: Fetch and search allowed without prompts
3030
- **Schema/warehouse/finops**: All inspection tools available
31+
- **Workspace knowledge**: Loads workspace and project skills; reads workspace memory and views this checkout's memory audit log. Reloading memory syncs the local copy with the workspace, which can remove a local copy of a block the workspace archived. Saving memory is done with `builder`.
3132

3233
!!! tip
3334
Use `analyst` when exploring data to ensure no accidental writes. Switch to `builder` when you're ready to create or modify models.

‎docs/docs/data-engineering/agent-modes.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -134,6 +134,7 @@ Estimated savings: ~60 credits/week (71% reduction on this query alone)
134134
- Search warehouse metadata
135135
- Detect PII columns
136136
- Save training entries
137+
- Read and reload workspace memory, view this checkout's memory audit log, and answer questions about team conventions from workspace skills (saving memory is done with builder)
137138

138139
---
139140

‎packages/opencode/src/agent/agent.ts‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -334,6 +334,13 @@ export const layer = Layer.effect(
334334
question: "allow",
335335
// Skills return instruction text only (no side effects), so they are safe for a read-only agent.
336336
skill: "allow",
337+
// Workspace memory: read, reload and view the audit log. Reloading syncs like the
338+
// load every session runs (it can drop a local copy of a block the workspace has
339+
// archived), but cannot create or edit memory. Saving and deleting stay denied, so a
340+
// decision is recorded through builder.
341+
altimate_memory_read: "allow",
342+
altimate_memory_refresh: "allow",
343+
altimate_memory_audit: "allow",
337344
// Delegation is limited to the read-only data-explorer subagent: general/explore/build
338345
// carry broader permissions than analyst, and children do not inherit parent-agent limits.
339346
task: {

‎packages/opencode/src/altimate/prompts/analyst.txt‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,10 @@ Treat inferred text labels as data: fixed rubric, stable IDs, coverage and dupli
1010
Use selected columns, partition filters and LIMIT/sampling to inspect cheaply; estimates are not exact final computations. Read JSONL spill paths with `read`; spills contain returned rows, not necessarily all matches. Aggregate in SQL for exact answers. On timeout, revise the query. Report costs only from evidence.
1111

1212
## Skills
13-
Use `skill` when available: /data-question, /cost-report, /query-optimize, /sql-translate, /dbt-analyze, /lineage-diff, /data-viz. File-writing steps require the builder agent.
13+
Use `skill` when available. When the skill list in your system prompt has one matching the request, load it, following the list's source precedence; workspace and project skills are included. Built-in data skills include /data-question, /cost-report, /query-optimize, /sql-translate, /dbt-analyze, /lineage-diff and /data-viz. File-writing steps require the builder agent.
14+
15+
## Workspace knowledge
16+
A question about the team's conventions, standards or past decisions is answered from workspace skills and memory, not from warehouse data: load the matching skill, check `altimate_memory_read` when it is in your tool list, and reply in plain text that states what was found or that nothing was found. Such a reply is not a data value, so do not finish it with `answer_commit`. You cannot save workspace memory blocks; when asked to save a team decision or convention, say that the builder agent can. A correction to your own behavior is still saved with `training_save`, as below.
1417

1518
## Teammate Training
1619
You are a trainable AI teammate. Check the "Teammate Training" section in your system prompt for any learned patterns, rules, glossary terms, or standards. Always apply learned training when relevant.
@@ -20,4 +23,4 @@ Use `training_list` to review learned knowledge. Skills: /teach, /train, /traini
2023

2124
When the request supplies an output JSON schema (the `StructuredOutput` tool is available), finish with `StructuredOutput` instead of `answer_commit` or a plain-text reply; follow that schema. The text finalization rules below apply when no output schema is supplied.
2225

23-
Finish by calling `answer_commit` with the single chosen value(s) with one field per item the request asks for (every named item, such as an entity and its related item or count, must be its own field: when the request asks for only the answer, anything left in the basis or prose is dropped), a one-or-two-sentence basis (population, grain, source object/column), or `unresolved` with the reason, then reply with exactly the text it returns and nothing else. Always supply `basis`, even when unresolved; it is never shown when the request asks for only the answer. Never list excluded candidates or alternative answers; a top-N with a tie at the boundary still returns N concrete rows (note the tie briefly in `rows.note`); when the request asks for only the answer or a specific format, set `answer_only`. If `answer_commit` is unavailable, finish with one or two sentences of basis and a final line `**Answer:** <requested value(s), with units>`, or `**Answer:** unable to determine — <why>`; when the request asks for only the answer or a specific format, the final message is exactly the requested value(s) or table in the requested format, with no label and no basis (or `unable to determine — <why>` if unresolved); never guess.
26+
For a data question, finish by calling `answer_commit` with the single chosen value(s) with one field per item the request asks for (every named item, such as an entity and its related item or count, must be its own field: when the request asks for only the answer, anything left in the basis or prose is dropped), a one-or-two-sentence basis (population, grain, source object/column), or `unresolved` with the reason, then reply with exactly the text it returns and nothing else. Always supply `basis`, even when unresolved; it is never shown when the request asks for only the answer. Never list excluded candidates or alternative answers; a top-N with a tie at the boundary still returns N concrete rows (note the tie briefly in `rows.note`); when the request asks for only the answer or a specific format, set `answer_only`. If `answer_commit` is unavailable, finish with one or two sentences of basis and a final line `**Answer:** <requested value(s), with units>`, or `**Answer:** unable to determine — <why>`; when the request asks for only the answer or a specific format, the final message is exactly the requested value(s) or table in the requested format, with no label and no basis (or `unable to determine — <why>` if unresolved); never guess.

‎packages/opencode/src/altimate/workspace/identity.ts‎

Lines changed: 32 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -85,6 +85,9 @@ export type RenderOptions = {
8585
* which store is the team's. `systemSection` derives it from the enablement memo;
8686
* the pure formatter takes it as an argument so tests stay deterministic. */
8787
teamMemory?: boolean
88+
/** Which memory tools the current agent may call. Defaults to both: the line names
89+
* `altimate_memory_write`, and an agent that cannot call it must not be told to. */
90+
memoryTools?: MemoryTools
8891
/** For `unknown`: no Altimate account is configured, so nothing could be checked. */
8992
noAccount?: boolean
9093
/** For `unknown`: an IDE pin governs this process, so the extension's selection is the thing to check. */
@@ -94,12 +97,31 @@ export type RenderOptions = {
9497
/** Two stores answer "remember this". Only one is read by other linked checkouts,
9598
* and nothing told the model which — so on a plain "save this for the team" it
9699
* reached for the engine's hub and the decision never left the session (#1332). */
97-
const TEAM_MEMORY_LINE =
100+
const TEAM_MEMORY_SAVE_LINE =
98101
"Team memory: save decisions and conventions with `altimate_memory_write` (scope " +
99102
'"project" for this project, "global" for everything); they sync to the workspace and to every ' +
100103
"linked checkout. The `datamate_*` memory tools (`datamate_add_memories`, `datamate_search_memory`) " +
101-
"are the engine's separate store and are not what teammates' sessions read. Before saving, check " +
102-
"`altimate_memory_read` for an existing block on the same subject and update it rather than add a duplicate."
104+
"are the engine's separate store and are not what teammates' sessions read."
105+
106+
/** Appended only when the agent can also read, since it names the read tool. */
107+
const TEAM_MEMORY_DEDUP_HINT =
108+
" Before saving, check `altimate_memory_read` for an existing block on the same subject and update " +
109+
"it rather than add a duplicate."
110+
111+
/** For an agent that can read memory but not save it (analyst): point it at the read tool,
112+
* and say where saving happens instead of naming a tool it does not have. */
113+
const TEAM_MEMORY_READ_ONLY_LINE =
114+
"Team memory: look up the workspace's saved decisions and conventions with `altimate_memory_read`. " +
115+
"This agent cannot save workspace memory blocks; when asked to save a decision or " +
116+
"convention for the team, say that an agent with memory write access, such as builder, can."
117+
118+
export type MemoryTools = { read: boolean; write: boolean }
119+
120+
function teamMemoryLine(tools: MemoryTools = { read: true, write: true }): string | undefined {
121+
if (tools.write) return tools.read ? TEAM_MEMORY_SAVE_LINE + TEAM_MEMORY_DEDUP_HINT : TEAM_MEMORY_SAVE_LINE
122+
if (tools.read) return TEAM_MEMORY_READ_ONLY_LINE
123+
return undefined
124+
}
103125

104126
function renderBody(outcome: BindingOutcome, opts: RenderOptions = {}): string {
105127
if (outcome.status === "bound") {
@@ -117,6 +139,7 @@ function renderBody(outcome: BindingOutcome, opts: RenderOptions = {}): string {
117139
? "This session was last known to be pinned by the IDE extension to"
118140
: "This project was last known to be linked to"
119141
const verifyNoun = pinned ? "pin" : "link"
142+
const memoryLine = opts.teamMemory ? teamMemoryLine(opts.memoryTools) : undefined
120143
return [
121144
HEADING,
122145
"",
@@ -128,7 +151,7 @@ function renderBody(outcome: BindingOutcome, opts: RenderOptions = {}): string {
128151
? " Skills and memory follow this workspace, and so does warehouse tool routing unless " +
129152
"integrations are set to local, even where the project's own link names a different one."
130153
: ""),
131-
...(opts.teamMemory ? [TEAM_MEMORY_LINE] : []),
154+
...(memoryLine ? [memoryLine] : []),
132155
`When ${TRIGGER}, the answer is this Altimate Workspace — never substitute ` +
133156
"another service's own \"workspace\" (a Databricks workspace, an IDE's " +
134157
"workspace folder, etc.) for it, and the reverse: a question about another " +
@@ -342,13 +365,13 @@ function governingPin(directory: string): boolean {
342365
return pin.kind === "valid" && resolveWithinRoot(directory, pin.root) !== null
343366
}
344367

345-
function renderOptions(outcome: BindingOutcome, directory: string): RenderOptions {
368+
function renderOptions(outcome: BindingOutcome, directory: string, memoryTools?: MemoryTools): RenderOptions {
346369
if (outcome.status === "unknown") return { pinned: governingPin(directory) }
347370
if (outcome.status !== "bound") return {}
348371
// A stale outcome is "last known … may since have changed": promising that a
349372
// save syncs to that workspace would contradict the line above it.
350373
if (outcome.stale) return {}
351-
return { teamMemory: memoryEnabledCached(outcome.binding) === "enabled" }
374+
return { teamMemory: memoryEnabledCached(outcome.binding) === "enabled", memoryTools }
352375
}
353376

354377
function keyFor(scope: AccountScope, directory: string): string {
@@ -415,7 +438,7 @@ async function withContents(outcome: BindingOutcome, directory: string, identity
415438
return contents ? `${identity}\n\n${contents}` : identity
416439
}
417440

418-
export async function systemSection(): Promise<string> {
441+
export async function systemSection(opts: { memoryTools?: MemoryTools } = {}): Promise<string> {
419442
// Behind the same opt-in as everything else about workspaces. A user outside
420443
// the pilot has no Altimate Workspace to be linked to, and must not be told
421444
// every turn that none is linked and how to link one.
@@ -443,15 +466,15 @@ export async function systemSection(): Promise<string> {
443466
})
444467
const key = keyFor(scope, directory)
445468
const hit = memo.get(key)
446-
if (fresh(hit)) return withContents(hit!.outcome, directory, render(hit!.outcome, MAX_SECTION_CHARS, renderOptions(hit!.outcome, directory)))
469+
if (fresh(hit)) return withContents(hit!.outcome, directory, render(hit!.outcome, MAX_SECTION_CHARS, renderOptions(hit!.outcome, directory, opts.memoryTools)))
447470
// The fallback is itself raced against a small budget, so the wait is
448471
// bounded by RESOLVE_DEADLINE_MS + FALLBACK_BUDGET_MS, not by the disk.
449472
const deadline = after(RESOLVE_DEADLINE_MS, () =>
450473
Promise.race([lastKnown(key, directory), after(FALLBACK_BUDGET_MS, () => ({ status: "unknown" }))]),
451474
)
452475
try {
453476
const outcome = await Promise.race([resolve(key, directory), deadline])
454-
return withContents(outcome, directory, render(outcome, MAX_SECTION_CHARS, renderOptions(outcome, directory)))
477+
return withContents(outcome, directory, render(outcome, MAX_SECTION_CHARS, renderOptions(outcome, directory, opts.memoryTools)))
455478
} finally {
456479
for (const t of timers) clearTimeout(t)
457480
}

‎packages/opencode/src/memory/tools/memory-read.ts‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -107,7 +107,9 @@ export const MemoryReadTool = Tool.define("altimate_memory_read", {
107107
return {
108108
title: "Memory: empty",
109109
metadata: { count: 0 },
110-
output: "No memory blocks found. Use altimate_memory_write to save information for future sessions.",
110+
// Read-only agents (analyst) call this tool too, so the result must not
111+
// direct them to a save tool they cannot call.
112+
output: "No memory blocks found.",
111113
}
112114
}
113115

‎packages/opencode/src/memory/tools/memory-refresh.ts‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,8 @@ export const MemoryRefreshTool = Tool.define("altimate_memory_refresh", {
2020
"workspace memory once at start; anything written after that is invisible",
2121
"until this runs.",
2222
"",
23-
"Does nothing when the project is not linked to a workspace.",
23+
"Does nothing when the project is not linked to a workspace. May remove local",
24+
"copies of blocks the workspace has archived; never creates or edits memory.",
2425
].join("\n"),
2526
parameters: z.object({}),
2627
async execute(_args, ctx) {

‎packages/opencode/src/session/llm.ts‎

Lines changed: 9 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -473,15 +473,18 @@ export namespace LLM {
473473
})
474474
}
475475

476+
// altimate_change start — one removal rule shared with prompt text that names tools
477+
// Tools removed before the model call: denied by the agent, or switched off on the request.
478+
export function removedTools(names: string[], input: Pick<StreamInput, "agent" | "user">): Set<string> {
479+
const disabled = PermissionNext.disabled(names, input.agent.permission)
480+
return new Set(names.filter((tool) => input.user.tools?.[tool] === false || disabled.has(tool)))
481+
}
482+
476483
async function resolveTools(input: Pick<StreamInput, "tools" | "agent" | "user">) {
477-
const disabled = PermissionNext.disabled(Object.keys(input.tools), input.agent.permission)
478-
for (const tool of Object.keys(input.tools)) {
479-
if (input.user.tools?.[tool] === false || disabled.has(tool)) {
480-
delete input.tools[tool]
481-
}
482-
}
484+
for (const tool of removedTools(Object.keys(input.tools), input)) delete input.tools[tool]
483485
return input.tools
484486
}
487+
// altimate_change end
485488

486489
// altimate_change start — collect tool names from message history to prevent API validation errors
487490
// Anthropic API requires every tool_use block in message history to have a matching tool

‎packages/opencode/src/session/prompt.ts‎

Lines changed: 14 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1922,7 +1922,20 @@ export namespace SessionPrompt {
19221922
// pure link identity. `systemSection()` reads `Instance.directory` itself, inside
19231923
// its own try/catch — NOT passed as an argument here — so a missing instance
19241924
// context can't throw synchronously at this call site.
1925-
const workspaceIdentity = await WorkspaceIdentity.systemSection()
1925+
// The team-memory line names memory tools; describe only the ones this agent and request
1926+
// keep. Steps that send no tools at all (answer echo, budget finalization) withhold every
1927+
// tool this prompt names, not just these, and are handled on their own paths.
1928+
const memoryRemoved = LLM.removedTools(["altimate_memory_read", "altimate_memory_write"], {
1929+
agent,
1930+
user: lastUser,
1931+
})
1932+
const memoryCallable = (name: string) => name in tools && !memoryRemoved.has(name)
1933+
const workspaceIdentity = await WorkspaceIdentity.systemSection({
1934+
memoryTools: {
1935+
read: memoryCallable("altimate_memory_read"),
1936+
write: memoryCallable("altimate_memory_write"),
1937+
},
1938+
})
19261939
// altimate_change end
19271940
// altimate_change start — workspace tool awareness.
19281941
// Reads the snapshot `Precedence.refresh` stored for this turn during tool

‎packages/opencode/test/agent/analyst-data-explorer.test.ts‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -75,6 +75,25 @@ it.instance("analyst can load skills", () =>
7575
}),
7676
)
7777

78+
it.instance("analyst can read workspace memory but not save, extract or delete it", () =>
79+
Effect.gen(function* () {
80+
const analyst = (yield* Agent.use.get("analyst"))!
81+
const builder = (yield* Agent.use.get("builder"))!
82+
const de = (yield* Agent.use.get("data-explorer"))!
83+
const read = ["altimate_memory_read", "altimate_memory_refresh", "altimate_memory_audit"]
84+
const write = ["altimate_memory_write", "altimate_memory_delete", "altimate_memory_extract"]
85+
for (const tool of read) expect(action(analyst, tool)).toBe("allow")
86+
for (const tool of write) expect(action(analyst, tool)).toBe("deny")
87+
expect(Permission.disabled([...read, ...write], analyst.permission)).toEqual(new Set(write))
88+
// The data-explorer subagent stays limited to warehouse and file reads.
89+
for (const tool of [...read, ...write]) expect(action(de, tool)).toBe("deny")
90+
for (const tool of ["altimate_memory_read", "altimate_memory_write"]) expect(action(builder, tool)).toBe("allow")
91+
// Reading memory does not loosen the rest of analyst's read-only policy.
92+
expect(action(analyst, "bash")).toBe("deny")
93+
expect(action(analyst, "sql_execute_write")).toBe("deny")
94+
}),
95+
)
96+
7897
it.instance("analyst may delegate only to data-explorer", () =>
7998
Effect.gen(function* () {
8099
const analyst = yield* Agent.use.get("analyst")

0 commit comments

Comments
 (0)