[oratis]

Summary

W2a of docs/PLAN_ALWAYS_ON_UPGRADE_2026-09-30.md: a deterministic layer that decides every tool call on the web surface, with scoped grants, an audit log and an approval inbox.

• Warden is opt-in. lisa serve --web with no flag behaves exactly as before (auto). --approval warden, or LISA_APPROVAL=warden for an app-launched backend, turns it on. The CLI REPL is unchanged.
• With Warden on, a side-effecting tool call that the policy will not auto-allow waits for the user's answer instead of being denied. Approve runs it; deny, expiry (10 minutes), a cancelled turn, a shutdown or a restart do not.
• Nothing is merged, deployed or published by this PR.

Why it stays opt-in

Only the web client renders an approval card, and over HTTP on loopback the server cannot tell the user's browser from a local process. A process the user runs unsandboxed can read an approval and approve it. Until approvals are signed by a native approver (the Mac app with a Keychain-bound key, or a paired phone), Warden protects against a model that has not been given an unconfined shell, not against one that has. That approver, and a real workspace root under launchd and Lisa.app, gate flipping the default.

Design

src/warden/ — no model calls, no I/O in the policy.

File	Role
types.ts	Categories, data classes, behaviours, origins, grants, inbox events
classify.ts, paths.ts	Explicit table: tool + input → category, targets, sandboxed, taint source; symlink-aware paths
preview.ts	HMAC payload digest, short redacted preview, full card payload, data-class detection
policy.ts	evaluate(req, ctx) — pure
rules.ts, grants.ts, taint.ts, audit.ts, store.ts	State under <lisaHome>/warden/, mode 0600
inbox.ts	Pending approvals per tenant, full payload in memory, durable mirror, expiry
session.ts	createWardenSession — the integration point

Evaluation order: system invariants → a handoff rule → grants (narrowed by what the request is) → forced asks → user rules → default matrix → context floor.

System invariants (not overridable by rules, grants or envelopes)

• purchase and credential are always handed back to the user.
• Origin autonomy may only read and write Lisa's own home; everything else is denied and never raises an approval.
• The cloud surface never allows exec or a host file write.
• Warden's state directory cannot be written or deleted by a file tool. The check follows symlinks and ignores case.

Default matrix

Category	Chat	Chat after taint	Task / routine / watcher	Channel / MCP / remote device
read, self, draft	auto	auto (see forced asks)	auto	auto
write inside a sandboxed workspace	auto	ask	preapproved	ask
write with no sandbox, or outside the workspace	ask	ask	ask	ask
exec, sandboxed	auto	ask	preapproved	ask
exec, no sandbox	ask	ask	ask	ask
network (non-read)	auto	ask	preapproved	ask
send, publish, delete	ask	ask	preapproved	ask
purchase, credential	handoff	handoff	handoff	handoff

Unsandboxed exec asks for every origin, the local owner included; a user who wants the old behaviour sets tools.bash = auto.

Forced asks

• Sensitive data to a recipient with no bound grant.
• In a tainted run: a fetch, ingest, browser-open or MCP call to an address that did not appear verbatim in the conversation.
• Any read, write or delete of a credential location (~/.ssh, ~/.aws, <lisaHome>/warden, …).
• In a tainted run: a read outside the workspace, and any skill_manage write.
• A command that names Warden's state, its approval API or its CLI — once, for that exact command.

Grants and the card

• Grants: once, task, target, 24h, always. Exact match on tool, category, method and trust column. A target grant needs every target covered, and is not offered when the targets cannot be enumerated.
• Tool-wide grants do not survive taint for side effects. A shell card never offers always or 24h. A user rule stricter than a grant wins.
• The card shows the whole payload (GET /api/approvals/{id}), in the classifier's order, and approving requires the digest of what was shown.

Full detail, the taint sources and the known limits are in docs/DESIGN_WARDEN.md.

Integration points

createWardenSession(opts: {
  surface: RuntimeSurface; uid: string | null; origin: Origin; taskId?: string;
  sandboxMode: SandboxMode; workspaceRoot: string; inbox: WardenInbox;
  tools?: ToolDefinition[]; envelope?: TaskEnvelope; purpose?: string;
  initialTaint?: boolean; onTaint?: () => void;
  knownUrls?: KnownUrls; userText?: string; home?: string;
  loadRules?: () => Promise<LoadedRules>; loadGrants?: () => Promise<LoadedGrants>;
  approvalTimeoutMs?: number; signal?: AbortSignal;
  dataClassHints?: DataClass[]; log?: (msg: string) => void; now?: () => number;
}): {
  approval: ApprovalCallback;       // pass to runAgent({ approval }) and to toolCtx.approval
  observe(event: AgentEvent): void; // feed from runAgent({ onEvent })
  decide(toolName, toolInput): Promise<{ decision, request, verdict }>;
  readonly tainted: boolean;
}

Inbox emitter: new WardenInbox({ emit: (event, uid) => void }). The host must deliver each event only to subscribers of that uid.

• approval_requested { type, id, kind: "approval"|"handoff", at, tool, category, targets, preview, purpose?, digest, expiresAt, taskId?, origin, reason, scopes }
• approval_resolved { type, id, verdict: "approved"|"denied"|"expired"|"dismissed", scope? }

HTTP API (in contracts/lisa-api-v1.openapi.json, additive)

Route	Notes
GET /api/approvals	Pending items for the caller's tenant, short previews, plus canApprove
GET /api/approvals/{id}	One item with its whole payload; approvers only
POST /api/approvals/{id}/approve	Body { digest, scope? }; digest is required
POST /api/approvals/{id}/deny	Body { reason? }; dismisses a handoff
GET / PUT /api/warden/rules
GET /api/warden/grants, DELETE /api/warden/grants/{id}
GET /api/warden/audit?limit=	Newest first, at most 500

State-changing routes require the loopback owner (Mac edition) or a signed-in per-user session, a JSON content type, and a same-origin request.

CLI: lisa approvals [list | show <id> | approve <id> --digest <digest> [--scope …] | deny <id>], lisa warden rules|grants|audit.

Review round (findings against 29b21a5)

All thirteen findings and the four lows are addressed; each has a regression test named review N. Summary:

• A. Opt-in; LISA_APPROVAL accepted.
• 1. Own-property rule lookups; an unknown behaviour ranks as ask.
• 2. review_diff no longer passes its target as an option. The same class was fixed in npm_info, speak and the yt-dlp adapter; the audit of the other read/self tools is recorded as tests.
• 3. Sandbox profiles deny Warden's directory and the server port; unsandboxed exec and writes ask by default.
• 4. Tainted egress asks unless the exact URL appeared in the conversation.
• 5. The card shows the whole payload; approving requires its digest.
• 6. Incomplete targets; target grants need full coverage; guarded exec is once-only.
• 7. More taint sources; taint persisted per conversation.
• 8. Grants narrowed under taint and under explicit ask rules.
• 9. skill_manage asks in a tainted run.
• 10. MCP tools cannot classify themselves as read.
• 11. Protected paths resolved through symlinks, compared without case.
• 12. A target rule loosens only with full coverage.
• 13. Redaction, key-name-only previews, phone masking, HMAC digest.

Changes outside src/warden/

• src/web/server.ts: the import, createWebWarden(...), the handleWardenApi hook, the per-turn session, the sandbox port registration, inbox shutdown, and an optional provider option used by the wiring test.
• src/sandbox/: protect.ts, and the denials in the seatbelt and bwrap profiles.
• src/tools/review_diff.ts, npm_info.ts, github.ts, src/voice/speak.ts, src/kb/ingest/adapters/ytdlp.ts: option-injection fixes.
• src/cli.ts, src/cli-args.ts, src/runtime-policy.ts, src/approval.ts: the mode and the subcommands.
• src/types.ts, src/subagent.ts, src/tools/task.ts: the approval hand-down to subagents.
• Some of these files also carry Prettier-only changes, because the format gate applies to every touched file.

Tests run

All local gates pass on Node 26: typecheck, typecheck:client, lint (0 errors), format:check, build, check:api-contract, check-md-links, and npm test — 2521 pass, 0 fail, 1 skipped (the existing node-pty test). 183 of those are this PR's.

Not done / known limits

• No native approver; a process the user runs unsandboxed can approve over loopback (see above).
• The workspace root is the server's working directory, which is / under launchd and Lisa.app.
• The string checks (commands naming Warden, shell commands reaching the network) are best effort.
• On Linux, bubblewrap cannot block one TCP port when the network is allowed.
• In a tainted run memory, soul_patch, kb_write and kb_add are still auto; the audit log marks them.
• read, grep and kb_read inside the workspace do not taint.
• Known URLs are kept in memory and lost on restart.
• --approval warden in the CLI REPL leaves the task subagent ungated.
• Only web chat turns are wired; IM channels, heartbeat and idle runs and managed agents are not.
• No iOS, Island or IM approval UI; a paired device token cannot approve.
• The inbox waiter is in-process (single instance).
• A pending approval produces SSE events only; a push for it goes through reachOut() in the integration PR.

🤖 Generated with Claude Code