Metadata-Version: 2.5
Name: dreameros-hooks
Version: 0.1.0a2
Summary: DreamerOS governance primitives as Claude Code hooks and SDK MCP tools.
License: MIT License
        
        Copyright (c) 2026 DreamerOS
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic>=2.0
Description-Content-Type: text/markdown

# @dreameros/hooks

DreamerOS governance primitives shipped as Claude Code hooks, skills, and an in-process SDK MCP server.

> Models generate. DreamerOS governs. Human decides.

## What you get

- **DAIM PreToolUse hook** - input rewriting, em-dash strip, injection check, depth proportionality
- **IFP three-axis PostToolUse hook** - Fidelity, Consequence, Endgame verification
- **EDE UserPromptSubmit hook** - intent archaeology and prompt restructuring
- **Mind's Eye additionalContext injector** - depth-calibrated response composition
- **DRM SubagentStop hook** - automatic cross-engine memory sync via DRM:: tag protocol
- **Skill pack**: `/ifp-verify`, `/daim`, `/ede`, `/mind-eye`, `/constellation-route`
- **In-process SDK MCP server** exposing all of the above as Agent SDK tools

## Install

### TypeScript / Node
```bash
npm install @dreameros/hooks
npx @dreameros/hooks init
```

### Python
```bash
pip install dreameros-hooks
python -m dreameros_hooks init
```

Both `init` commands drop a `.claude/hooks.json` and `.claude/skills/` tree in the current repo, wired to the public DreamerOS gateway by default. Set `DREAMEROS_GATEWAY_URL` and `DREAMEROS_API_KEY` to point at a self-hosted gateway.

## Tiers

- **Free** - 100 invocations/day, phone-home telemetry on
- **Pro** - $20/mo, unlimited, cloud SCS
- **Elite** - SOC2, IFP audit log, Trust Wall, per-org SCS

See https://dreameros.app/pricing.

## License

MIT. The wedge is permissive on purpose. The gateway core (where the verifiers actually run) is BSL 1.1.

## Status

Phase 1 scaffold. Not yet production. See `governance/proposed/CLAUDE_PLATFORM_DISRUPTION_MAP_2026_05_12.md` for the full execution plan.

## Subagent dispatch hygiene

Hosts using `@dreameros/hooks` to dispatch subagents inherit the gateway's bounded-execution canon. Spec at `governance/00_CORE/BOUNDED_EXECUTION_DISCIPLINE_v1_0_0.md` (LIVING_INDEX entry, sha256 `8c52dab59f3b592b8dcfb0f2f645930b9a8a05005088bbea467cf4c8a3773233`).

The strongest rule: every long-running call carries an exit bound. When this SDK fans out work to a subagent or schedules a long-running tool call, the dispatcher must include the bound in the prompt or call:

- Subagent prompt: "if 5 min no progress, report PARTIAL and STOP, no loop, no retry past 2 attempts."
- Tool call: explicit `timeout` plus an inner `curl --max-time` or equivalent.
- Watch loop: prefer a `Monitor`-style until-loop over a polling background process.
- Engine fan-out: prefer single-engine routing over multi-engine consensus unless the claim demands cross-check.

The DRM `SubagentStop` hook persists the subagent result, but the bound is what guarantees the hook ever runs. Without the bound the subagent can wait indefinitely and the `Stop` event never fires.

Operator vocabulary that invokes this contract: "bound this", "add a 5-min self-terminate", "sub-agent it" (the bound contract auto-applies per the agent definition). Full primer at substrate memory `9398acdc-6bb7-4709-abad-a7bcb44ff265` (OPERATOR_VOCABULARY_PRIMER_v1_0_0).

## Modality-Routed Governance + Connector-as-Turn + SAIP

Hosts using `@dreameros/hooks` inherit three additional canon contracts ratified 2026-06-26. Specs:

- `governance/00_CORE/MODALITY_ROUTED_GOVERNANCE_v1_0_0.md` (sha256 `85192d98fa10e46015256dc4f9d7f791ca1e80592d39f0658ae62b15fb2317d3`).
- `governance/00_CORE/CONNECTOR_AS_TURN_v1_0_0.md` (sha256 `93b912a70117d7e853c69a51350564263fa74676fd81477871a3a19c4918072d`).
- `governance/00_CORE/SENSE_AGNOSTIC_INTEGRITY_PROTOCOL_v1_0_0.md` (sha256 `8f2a9a983f4b70c6816c55792cd19597dde160392806e955eff8c074c31324b9`).

What the SDK consumer must respect:

- **MRG.** When the host dispatches a multi-engine fan-out (consensus, compare, constellation), the routing decision is itself a governed event. Each contributor call carries the modality tag, the EDE detected intent, and an inner bound per BOUNDED_EXECUTION_DISCIPLINE.
- **CaT.** When the host wires a connector (OAuth pull, paste-token, MCP read, scheduled sync), the ingest path must fire the 9-step pattern (source-attest, EDE, DAIM, IFP fence, modality-route, write, CTCI receipt, governance event, observable failure) before any byte lands in substrate or the system-prompt block. The `connector_ifp_gate._evaluate` extension point is the integration seam.
- **SAIP.** Every input modality (text, voice, image, file, snapshot, connector) inherits the IFP Five Pillars per the modality coverage matrix in the SAIP spec. The host must not silently absorb non-text content; voice goes through ASR plus the text-side gates, image goes through DAIM plus IFP fence on prompt and pixel content, file goes through EDE plus DAIM plus IFP fence plus CTCI receipt.

Operator vocabulary that invokes the trinity: "route this by strength" (MRG), "make this connector a turn" (CaT), "make this sense-agnostic" (SAIP). Full primer at substrate memory `9398acdc-6bb7-4709-abad-a7bcb44ff265` (OPERATOR_VOCABULARY_PRIMER_v1_0_0).

## CI/CD Operator Primer

Hosts using `@dreameros/hooks` to drive a ship from PR-open to runtime-live inherit the CI/CD Operator Primer canon. Spec at `governance/00_CORE/CI_CD_OPERATOR_PRIMER_v1_0_0.md` (sha256 `3e46ecd15e1a86aa92b5ab4fff5f56501682e9ca9a408876f99b69859f0d046c`). HOW-layer companion at `governance/04_OPERATIONS/crown_jewels_ci_cd_operator_primer_v1_0_0.md` (sha256 `4d5d6cf51e686ecab2c46ce017bc600a0eb417b58fb407c90ddf6685398fccb4`).

The single magic phrase: "Ship it and verify customer-usable end-to-end." That invokes the full seven-stage pipeline plus the P37 six-row walk plus the substrate write at the end.

The seven stages (each is a separate referent; skipping one is a P37-row-6 violation):

1. Code wired - imports resolve, lint clean.
2. PR opened - branch pushed, body cites intent and touch surface.
3. CI checks - every gate has a verdict on the head SHA.
4. Merged - auto-merge fired on green; the merge SHA is the new head.
5. Deploy fires - the host's deploy mechanism ran for the merge SHA.
6. Runtime live - a runtime signal on the deploy SHA exists (boot log, 200 on the affected route, fresh log line emitted by the change).
7. P37 customer-usable - the six-row walk returns PASS on every row.

Key verification commands an SDK consumer runs (full recipe in the HOW companion):

- CI verdict on a SHA: `mcp__github__pull_request_read` then `mcp__github__get_check_run` for each gate.
- Gateway deploy: `mcp__DreamerOS_Live__dreameros_railway action=deployments` - newest SUCCESS, `meta.commitHash` is the live SHA.
- Frontend deploy: `mcp__Vercel__list_deployments` then `mcp__Vercel__get_deployment` for `state=READY` on the merge SHA.
- Runtime log signal: `mcp__DreamerOS_Live__dreameros_railway action=logs deployment_id=<id>` then grep for the new behavior's log line.
- Substrate write at the end of every ship: `mcp__DreamerOS_Live__dreameros_remember` with `memory_type=procedural` and tags including `cold-start-anchor`, `next-session-read-first`, and `anti-rediscovery` when the ship produced new operational knowledge.

Operator vocabulary that invokes the contract: "ship it and verify customer-usable end-to-end" (full canon stack), "ship it" (stages 1 through 4 only, report PARTIAL), "is this live?" (stages 5 and 6 against a SHA, cite runtime signal), "walk the P37 on X" (six-row walk against X). Full primer at substrate memory `9398acdc-6bb7-4709-abad-a7bcb44ff265` (OPERATOR_VOCABULARY_PRIMER_v1_0_0).
