# Interaction Awareness — Developer Reference

Claude Code plugin for AI interaction pattern awareness.

## Architecture

Four layers, each building on the previous:

- **Layer 1** (`skills/`) — SKILL.md behavioral overrides. Always active.
- **Layer 2** (`hooks/scripts/`) — Programmatic detection via 4 hook events.
  Node.js (`.mjs`), cross-platform. Writes JSONL metadata to `${CLAUDE_PLUGIN_DATA}`.
- **Layer 3** (`commands/`) — User-triggered reports from Layer 2 data. Opt-in.
- **Layer 4** (`commands/interaction-report.md` Step 9) — Contemplative references. Opt-in.

## Key files

| File | Purpose |
|------|---------|
| `hooks/scripts/lib.mjs` | Shared library: stdin, paths, thresholds, state, cooldowns, layer guards |
| `hooks/scripts/session-start.mjs` | SessionStart: register session, count daily, night check |
| `hooks/scripts/prompt-analyzer.mjs` | UserPromptSubmit: pattern flags (NEVER logs prompt text) |
| `hooks/scripts/tool-tracker.mjs` | PostToolUse: events, edit ratio, burst, alerts |
| `hooks/scripts/session-end.mjs` | SessionEnd: finalize JSONL, cleanup state |
| `hooks/hooks.json` | Hook event registration (4 events) |
| `skills/ai-psychosis/SKILL.md` | Layer 1 behavioral instructions |
| `commands/interaction-report.md` | Layer 3 slash command: `/interaction-report [weekly\|monthly\|all]` |
| `hooks/scripts/report-reader.mjs` | Layer 3 helper: reads sessions.jsonl with v1.0.0 backward compat |

Legacy bash scripts were removed in v1.0 (available in git history).

## Data storage

```
${CLAUDE_PLUGIN_DATA}/
├── sessions.jsonl       Compact JSONL, one record per session
├── events.jsonl         {ts, session_id, tool_name} per tool call
└── state/
    └── {session_id}.json    Live state during active session
```

State files are created at SessionStart and deleted at SessionEnd.

## Hard constraints

- **Cross-platform** — Node.js only, no bash/jq dependency
- **Privacy** — prompt text NEVER written to disk. Boolean flags only.
- **Performance** — hooks must complete in <100ms
- **Non-blocking** — never exit 2, never require confirmation
- **No network** — everything local
- **Zero npm dependencies** — Node.js stdlib only (fs, path, os)

## Layer configuration

Global config at `~/.claude/ai-psychosis.local.md`, or per-project override at `<project>/.claude/ai-psychosis.local.md`:

```yaml
---
layer2: true   # default on
layer3: false  # default off
layer4: false  # default off
---
```

`requireLayer(N)` in lib.mjs exits with `{"continue": true}` if layer N is disabled.

## Testing

Automated test suite using `node:test` (126 cases, zero npm dependencies):

```bash
node --test tests/*.test.mjs
```

| File | Cases | Coverage |
|------|-------|----------|
| `tests/session-start.test.mjs` | 5 | State init, JSONL, missing sid |
| `tests/prompt-analyzer.test.mjs` | 93 | 41 (25 negative + 12 pushback + 4 domain) patterns × 2 + thresholds + valence |
| `tests/tool-tracker.test.mjs` | 8 | Counting, burst, reminders |
| `tests/session-end.test.mjs` | 6 | Finalize, duration, flags, v1.0.0 backward compat |
| `tests/privacy.test.mjs` | 2 | Canary string + matched-phrase leak guard |
| `tests/skill-md.test.mjs` | 1 | SKILL.md cites Constitution + 5-publication framework |
| `tests/perf.test.mjs` | 8 | 4 hooks × 2 modes — enforces <50ms logic / <200ms total |
| `tests/interaction-report.test.mjs` | 3 | report-reader.mjs reads JSONL with v1.0.0 backward compat |

## Conventions

- Conventional Commits: `type(scope): description`
- English for all code, comments, and documentation
- Norwegian for project-internal communication