trellis/decisions
Decision trace capture, querying, and audit trails for tool invocations and agent workflows.
Overview
The trellis/decisions subpath records tool invocations and agent decisions as auditable traces in the graph, enriched with rationale, entity links, and causal chains. The API and trellis decision CLI are available now; automatic capture from a standalone MCP server is still tracked as WIP.
import { queryDecisions, recordDecision } from "trellis/decisions";
recordDecision
Record a decision trace for a tool invocation:
const dec = await recordDecision(ctx, {
toolName: "trellis_issue_create",
input: { title: "Add TypeScript parser" },
output: { id: "issue:TRL-5" },
rationale: "Needed to support TS/JSX semantic diffing",
entityRefs: ["issue:TRL-5", "file:src/semantic/index.ts"],
});
// dec.id → 'decision:d42'
DecisionInput
interface DecisionInput {
toolName: string;
input: Record<string, unknown>;
output: Record<string, unknown>;
rationale?: string;
entityRefs?: string[]; // Entities this decision affects
parentId?: string; // Parent decision (for chains)
agentId?: string; // Override author identity
}
queryDecisions
Query the decision trace store:
// All decisions by a specific tool
const byTool = queryDecisions(ctx, { tool: "trellis_issue_create" });
// Wildcard tool match
const allIssueOps = queryDecisions(ctx, { tool: "trellis_issue_*" });
// Full decision chain for an entity
const chain = queryDecisions(ctx, { entity: "issue:TRL-5" });
// Decisions in a time window
const recent = queryDecisions(ctx, {
since: "2026-01-01",
until: "2026-04-01",
limit: 50,
});
Query Options
interface DecisionQuery {
tool?: string; // Exact match or glob pattern ('trellis_issue_*')
entity?: string; // Entity ID — returns full chain
agentId?: string; // Filter by author
since?: string; // ISO 8601 date
until?: string; // ISO 8601 date
limit?: number; // Default: 100
}
Decision Chains
When one decision causes another (e.g., creating an issue triggers auto-branching), they form a chain via parentId:
const chain = queryDecisions(ctx, { entity: "issue:TRL-5" });
// Returns the full tree: issue_create → branch_create → milestone_create
Inspect the chain with the CLI:
trellis decision chain issue:TRL-5
CLI
trellis decision list # List recent decision traces
trellis decision list --tool trellis_issue_* # Filter by tool pattern
trellis decision show <id> # Full decision detail
trellis decision chain issue:TRL-5 # Trace decisions for an entity
MCP Integration
MCP-backed automatic decision capture is a roadmap item. Until the standalone MCP command ships, use recordDecision directly or inspect traces created by a harness that already writes to the Trellis decision store.
Decision Entity Shape
interface DecisionEntity {
id: string; // 'decision:d<n>'
toolName: string;
input: string; // JSON-serialised
output: string; // JSON-serialised
rationale?: string;
entityRefs: string[]; // Linked entity IDs
parentId?: string;
agentId: string;
createdAt: string;
}