# GuangHu Codex Host Bridge v1

This package compiles a small host-side boundary for Codex tasks. It does not
define a persona, change model or platform rules, or grant repository/server
authority.

## What it enforces

- A direct human `UserPromptSubmit` advances one global current-controller
  epoch for the local Codex installation.
- Wrapped Codex task delegations are recorded as non-human delivery and never
  impersonate direct human speech or claim controller status.
- Capability tools in stale Codex tasks are denied by `PreToolUse`.
- Remote Git writes, external publishing/deployment, and destructive cleanup
  require a current-turn, exact-working-directory, time-limited one-shot lease.
- Hook commands pin the SHA-256 of installed runtime scripts. A changed script
  requires regeneration of the hook definition and visible Codex review.

## What is never published by this package

Runtime state stays under the local `CODEX_HOME`: raw messages, numbered
events, the current controller, leases, trust state, credentials and keys.
This repository contains only source, tests, installer logic and architecture
documentation.

## Install

```bash
node scripts/install.mjs \
  --subject-id "ICE-GL∞" \
  --subject-name "冰朔" \
  --carrier-role "CODEX_SUMMARY_PROMPTER_ONLY"
```

The installer preserves unrelated hooks, installs the runtime under
`$CODEX_HOME/runtime/guanghu-codex-host-bridge/v1`, and writes hash-pinned
`UserPromptSubmit` and `PreToolUse` entries. Codex must then visibly review and
trust the changed hook definitions.

Optional environment variables:

- `CODEX_HOME`: defaults to `~/.codex`.
- `GH_HUMAN_MEMORY_ANCHOR`: optional durable-memory pointer added to the thin
  source envelope; no memory body is copied.
- `GH_CODEX_CONTROL_ROOT`: overrides the local controller/lease state folder.

## Issue a one-shot lease

Only after explicit authorization in the current direct-human turn:

```bash
node "$CODEX_HOME/runtime/guanghu-codex-host-bridge/v1/write-lease.mjs" issue \
  --session-id '<current-session>' \
  --turn-id '<current-turn>' \
  --category remote_git \
  --cwd '/exact/repository/path' \
  --target 'origin/main' \
  --reason 'explicit current-turn authorization'
```

The next matching high-risk action consumes the lease before execution. A new
direct prompt, expiry, category mismatch, directory mismatch, session mismatch
or turn mismatch invalidates it.

## Test

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