trellis/decisions
Decision trace capture, querying, and audit trails for tool invocations and agent workflows.
Overview
The trellis/decisions subpath automatically captures tool invocations and agent decisions as auditable traces in the graph. Every time an MCP tool fires, a decision is recorded — enriched with rationale, entity links, and causal chains.
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
Visualise the chain with the CLI:
trellis agent inspect <run-id> # View run details and full decision chain
CLI
trellis agent list # List all agent runs
trellis agent create <name> # Register a new agent
trellis agent run <id> --input "task" # Execute an agent run
trellis agent inspect <run-id> # View run with full decision trace
MCP Integration
All MCP tools automatically record decisions. When an AI assistant invokes trellis_issue_create, a decision trace is written to the graph with the tool's input, output, and (if the agent provides it) rationale:
trellis decision list # List recent decision traces
trellis decision show <id> # Full decision detail
This gives you a complete audit trail of every AI-assisted action in your repository.
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;
}