slaude Guardrails — Design Document

~/.slaude/
├── POLICY.md                                # operator-authored, git-tracked
└── cache/
    └── policy/
        └── <embedding_model>/
            ├── policy.db                    # sqlite + sqlite-vec virtual table
            └── meta.json                    # {policy_sha, anchors_count, built_at}

---
version: 1
defaults:
  threshold: 0.65
  hook_points: [user_prompt, pre_tool, output]
embedding:
  provider: gemma                            # gemma | openai | bge-m3
  model: embeddinggemma-300m
  dim: 768
role_source:
  type: remote_http
  url: https://idp.internal/api/slack-roles
  auth: bearer ${ROLE_API_TOKEN}
  ttl_seconds: 600
onboarding:
  enabled: true
  message_template: |
    I don't have you in my role map yet. Onboard here: {{onboard_url}}.
    Manager <@{{manager_id}}> — please approve.
  manager_request_approval: true
---

# Rules

- id: leak-customer-pii
  severity: block
  roles_allowed: []
  roles_denied: [anonymous, vendor, intern]
  channels: [any]
  hook_points: [user_prompt, pre_tool, post_tool, output]
  threshold: 0.7
  anchors:
    - share customer credit card
    - borrower KTP number
    - phone number disclosure
  message: "PII handling restricted. Ask #compliance."

- id: discuss-roadmap-q3
  severity: ask
  roles_allowed: [manager, eng-lead, exec]
  roles_denied: [vendor, anonymous]
  channels: [trusted]
  threshold: 0.6
  anchors:
    - q3 roadmap
    - unreleased feature timeline
  message: "Roadmap topic — manager approval required."

- id: destructive-bash
  severity: block
  roles_allowed: [eng-lead, sre]
  channels: [trusted]
  hook_points: [pre_tool]
  threshold: 0.55
  anchors:
    - rm -rf production
    - drop table users
    - terraform destroy

CREATE TABLE policy_rules (
  id            TEXT PRIMARY KEY,
  severity      TEXT NOT NULL,
  roles_allowed JSON NOT NULL,
  roles_denied  JSON NOT NULL,
  channels      JSON NOT NULL,
  hook_points   JSON NOT NULL,
  threshold     REAL NOT NULL,
  message       TEXT,
  rule_sha      TEXT NOT NULL                -- detects rule body change
);

CREATE TABLE policy_anchors (
  id        INTEGER PRIMARY KEY AUTOINCREMENT,
  rule_id   TEXT NOT NULL REFERENCES policy_rules(id) ON DELETE CASCADE,
  text      TEXT NOT NULL,
  text_sha  TEXT NOT NULL,                   -- cache key for embedding
  UNIQUE(rule_id, text_sha)
);

CREATE VIRTUAL TABLE policy_vec_embeddinggemma_300m USING vec0(
  anchor_id INTEGER PRIMARY KEY,
  embedding FLOAT[768]
);

on boot OR file_watch(POLICY.md) fires:
  policy_text = read POLICY.md
  policy_sha = sha256(policy_text)
  if meta.json.policy_sha == policy_sha:
      load existing tables; return

  rules = parse_yaml(policy_text)
  begin txn:
    upsert policy_rules (by id, with rule_sha)
    delete rules not present in current POLICY.md
    for rule in rules:
      for anchor_text in rule.anchors:
        text_sha = sha256(anchor_text)
        if not exists policy_anchors(rule.id, text_sha):
          vec = embedding_provider.embed([anchor_text])[0]
          insert policy_anchors → anchor_id
          insert policy_vec_<model> (anchor_id, vec)
      delete policy_anchors for this rule not in current anchor list
        (cascades to policy_vec via trigger)
  commit
  write meta.json = {policy_sha, anchors_count, built_at}
  atomic-swap in-memory pointer to new loader instance

interface RoleResolver {
  resolve(slackUserId: string): Promise<ResolvedRole | null>
}

interface ResolvedRole {
  role: string                  // canonical role identifier
  groups: string[]              // optional secondary memberships
  resolved_at: number           // epoch ms
  stale_at: number              // epoch ms when cache entry expires
  source: string                // 'remote_http' | 'slack_usergroups' | 'soul_md' | 'null'
}

LRU<userId, ResolvedRole> in-memory, max 10K entries
TTL = resolved.stale_at - resolved.resolved_at, default 600s

<actor user="U02ABC" role="eng-lead" groups="payment,risk" channel_trust="trusted"/>

interface EmbeddingProvider {
  readonly model_id: string       // "embeddinggemma-300m"
  readonly dim: number            // 768
  readonly l2_normalized: boolean
  embed(texts: string[]): Promise<Float32Array[]>
}

// src/agent/hooks.ts — Agent loop
import type { HookContext } from '@anthropic-ai/claude-agent-sdk'
import { PolicyClient } from '../policy/client'

const policyClient = new PolicyClient('http://localhost:8081')

export const userPromptSubmitHook = async (ctx: HookContext) => {
  const actor = parseActorEnvelope(ctx.message.content)
  const decision = await policyClient.check({
    text: stripEnvelopes(ctx.message.content),
    actor,
    channel: actor.channel_trust,
    hook_point: 'user_prompt',
  })
  return applyDecision(decision, ctx, 'user_prompt')
}

export const preToolUseHook = async (ctx: HookContext) => {
  const actor = ctx.session.actor                  // resolved at session boot
  const text = serializeToolInput(ctx.tool.name, ctx.tool.input)
  const decision = await policyClient.check({
    text,
    actor,
    channel: ctx.session.channel_trust,
    hook_point: ctx.tool.name.startsWith('mcp__slaude_slack__') ? 'output' : 'pre_tool',
  })
  return applyDecision(decision, ctx, 'pre_tool')
}

export const postToolUseHook = async (ctx: HookContext) => {
  const actor = ctx.session.actor
  const decision = await policyClient.check({
    text: ctx.tool.result,
    actor,
    channel: ctx.session.channel_trust,
    hook_point: 'post_tool',
  })
  if (decision.action === 'redact') {
    return { result: redactSpans(ctx.tool.result, decision.spans) }
  }
  return applyDecision(decision, ctx, 'post_tool')
}

// src/policy/client.ts — Agent → policy-service client
export class PolicyClient {
  constructor(private baseUrl: string) {}

  async check(input: PolicyCheckInput): Promise<Decision> {
    const res = await fetch(`${this.baseUrl}/check`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(input),
      timeout: 500,  // policy checks must be fast
    })
    if (!res.ok) throw new Error(`Policy check failed: ${res.statusText}`)
    return res.json()
  }

  async reload(): Promise<void> {
    const res = await fetch(`${this.baseUrl}/reload`, { method: 'POST' })
    if (!res.ok) throw new Error(`Policy reload failed: ${res.statusText}`)
  }
}

### 6.3 Action × hook matrix

| Hook | `block` | `ask` | `redact` | `log` |
|---|---|---|---|---|
| `UserPromptSubmit` | replace prompt w/ rejection msg, short-circuit turn | inject `<approval-required rule="…">`, route to `request_approval` | regex/template scrub matched span | metric only |
| `PreToolUse` (bash/write/etc) | return `{decision: 'block', reason}` | return `{decision: 'ask'}` → `request_approval` | mutate args (rare) | metric only |
| `PreToolUse` on `mcp__slaude_slack__reply` | replace payload w/ refusal text | escalate via `request_approval` | redact PII in payload before post | metric only |
| `PostToolUse` | drop observation, replace w/ error stub | n/a (already executed) | scrub tool output before agent reads | metric only |

---

## 7. Decision Pipeline

### 7.1 `policyCheck()` signature

```typescript
interface PolicyCheckInput {
  text: string
  actor: ResolvedRole | { role: 'anonymous', groups: [], source: 'unknown' }
  channel: 'trusted' | 'allowed' | 'restricted'
  hook_point: 'user_prompt' | 'pre_tool' | 'post_tool' | 'output'
}

interface Decision {
  action: 'block' | 'ask' | 'redact' | 'log' | 'allow'
  rule_id?: string
  anchor_id?: number
  score?: number
  message?: string
  matched_rules: Array<{rule_id: string, anchor_id: number, score: number}>
}

async function policyCheck(input: PolicyCheckInput): Promise<Decision>

input: {text, actor, channel, hook_point}
  │
  ▼
query_vec = embedding_provider.embed([text])[0]
  │
  ▼
top-k 10 from policy_vec_<model> ordered by distance ASC
  │
  ▼
JOIN policy_anchors → policy_rules
  │
  ▼
filter:
  - hook_point ∈ rule.hook_points
  - similarity ≥ rule.threshold       (similarity = 1 - L2_distance/2 for L2-normalized)
  - actor.role ∉ rule.roles_denied
  - actor.role ∈ rule.roles_allowed OR rule.roles_allowed contains 'any'
  - channel ∈ rule.channels OR rule.channels contains 'any'
  │
  ▼
if any rule had actor.role ∈ roles_denied (regardless of allowed):
  upgrade severity to block        (denial is absolute)
  │
  ▼
reduce surviving rules → single action by severity precedence:
  block > ask > redact > log > allow
ties → lowest L2 distance wins (most semantically certain anchor)
  │
  ▼
emit Decision{action, rule_id, anchor_id, score, message, matched_rules}

explicit roles_denied hit  → severity escalates to block (overrides ask/redact)
multiple rules hit         → max(severity) wins
tied severity              → lowest anchor distance wins
no rule hits               → allow + sample-log (configurable rate, default 5% prod / 100% dev)

1. adapter.ts → resolve role = vendor → inject
     <actor user="Uvendor" role="vendor" channel_trust="allowed"/>
2. SDK UserPromptSubmit hook fires
3. embed("hey, what's the q3 roadmap looking like?") → query_vec
4. top-k anchors → "q3 roadmap" @ similarity 0.74 (rule discuss-roadmap-q3)
5. filter:
     - hook_point user_prompt ∈ rule.hook_points ✓
     - similarity 0.74 ≥ rule.threshold 0.6 ✓
     - vendor ∈ roles_denied [vendor, anonymous] → DENY trigger
     - vendor ∉ roles_allowed [manager, eng-lead, exec]
     - allowed ∈ rule.channels [trusted] ✗
   → rule's `ask` severity escalates to `block` due to roles_denied hit
6. action: block
7. hook returns prompt replacement:
     "Roadmap topic — restricted for your role. Ping #pm-team for public updates."
8. SDK turn ends without LLM call
9. metric: slaude_policy_blocks_total{rule="discuss-roadmap-q3",hook_point="user_prompt",role="vendor"} += 1

turn arrives → adapter.ts resolves role → null → assigned role=anonymous
  ↓
preflight policyCheck on inbound text
  ↓
if any rule triggers with severity ≥ ask (which is most rules for anonymous):
  short-circuit BEFORE SDK boot
  ↓
emit slaude_slack__reply with onboarding message:
  "I don't have you in my role map. Onboard here: <link>.
   Manager <@manager.userId> — please approve."
  ↓
if config.onboarding.manager_request_approval:
  post request_approval prompt to manager
  category: 'onboarding', summary: 'add user <@Uxxx> role'
  on approve → write to remote role source (via webhook or manual step)
  ↓
set pending-onboarding flag in sqlite per userId (TTL 24h)
  ↓
subsequent turns from same user while pending:
  drop with dedupe (post onboarding message once per dedup window 1h)

src/
  policy/                          # ← NEW: standalone policy-service module
    server.ts                      # Express/Hono HTTP server, routes: POST /check, /reload
    loader.ts                      # POLICY.md parse → Chroma build (sha-cached, hot-reload)
    check.ts                       # policyCheck() — embed query, rule filter, severity reduce
    store.ts                       # Chroma schema + vector store wrapper
    client.ts                      # HTTP client for agent to call policy-service
    types.ts                       # Rule, Anchor, Decision, PolicyCheckInput (shared types)
  embedding/                       # ← NEW: embedding providers (used by policy-service)
    provider.ts                    # EmbeddingProvider interface
    gemma.ts                       # GemmaEmbeddingProvider (default, local)
    openai.ts                      # OpenAIEmbeddingProvider
    bge.ts                         # BgeM3EmbeddingProvider
  roles/                           # ← NEW: role resolvers (used by both services)
    resolver.ts                    # RoleResolver interface
    remote-http.ts                 # RemoteHttpRoleResolver (default)
    soul-md.ts                     # SoulMdRoleResolver (fallback)
    null.ts                        # NullRoleResolver (dev)
    composite.ts                   # CompositeRoleResolver (chain)
    cache.ts                       # LRU + TTL + stale-while-revalidate

// src/server.ts
import { launchAgentManager } from './agent/manager'
import { launchPolicyService } from './policy/server'

async function main() {
  const policyMode = process.env.SLAUDE_POLICY_MODE === 'enabled'
  
  const policyPort = parseInt(process.env.SLAUDE_POLICY_PORT || '8081', 10)
  const agentPort = parseInt(process.env.PORT || '3000', 10)

  // Start policy-service first; if it fails, don't start agent
  if (policyMode) {
    await launchPolicyService({ port: policyPort })
    console.log(`Policy-service running on :${policyPort}`)
  }

  // Start agent; it calls policy-service if enabled
  await launchAgentManager({ port: agentPort, policyServiceUrl: policyMode ? `http://localhost:${policyPort}` : null })
  console.log(`Agent running on :${agentPort}`)
}

main().catch(err => {
  console.error('Startup failed:', err)
  process.exit(1)
})

slaude_policy_checks_total{hook_point, result}
  result: block | ask | redact | log | allow

slaude_policy_blocks_total{rule_id, hook_point, role, channel}
slaude_policy_asks_total{rule_id, hook_point, role, channel}
slaude_policy_redacts_total{rule_id, hook_point, role, channel}

slaude_policy_score_bucket{hook_point}   # histogram of top-1 similarity

slaude_policy_load_duration_seconds       # boot embed cost
slaude_policy_anchors_count{model}        # cache size
slaude_policy_reload_total{result}        # hot-reload success/failure

slaude_role_resolver_requests_total{source, result}
slaude_role_resolver_latency_seconds_bucket{source}
slaude_role_resolver_failures_total{source, kind}
slaude_role_resolver_cache_size

slaude_embedding_requests_total{provider, result}
slaude_embedding_latency_seconds_bucket{provider}

slaude_onboarding_redirects_total{reason}  # user_unknown | remote_down

// src/server.ts supervision logic
const child = spawn('node', ['build/policy-service-main.js'], {
  stdio: 'inherit',
  detached: false,
})

// Health check: poll policy-service before marking agent ready
async function waitForPolicyService(url: string, timeoutMs: number) {
  const deadline = Date.now() + timeoutMs
  while (Date.now() < deadline) {
    try {
      const res = await fetch(`${url}/health`, { timeout: 500 })
      if (res.ok) return true
    } catch (e) {
      // expected, not up yet
    }
    await new Promise(r => setTimeout(r, 100))
  }
  throw new Error(`Policy-service failed to start within ${timeoutMs}ms`)
}

// On agent startup: wait for policy-service if enabled
if (policyMode) {
  await waitForPolicyService(policyServiceUrl, 10000)
}