Skip to content

Record one real host's hook contract with sanitized fixtures #16

Open

Description

@tomjwxf

Why

src/cli-format.test.ts checks the built CLI's stdin, stdout and exit codes.
Several cross-host checks reuse a synthetic tool payload. Those tests are useful,
but do not establish what a particular host version sends or whether that host
actually stops a denied tool call.

Start with one supported host you already use: Claude Code, Cursor, Gemini
CLI, Hermes or a Codex environment that supports the documented hook interface.
Comment with the host and version before starting so contributors do not duplicate
the same capture. No paid account or service should be required just to run the
committed fixture tests.

Scope

  • Record the host version, OS, Node version, protect-mcp version and the exact
    project hook configuration.
  • Capture a permitted read and a denied harmless test action, with the input
    event, hook output, exit code and what the host displayed. Do not execute a
    destructive command to test a block.
  • Use a disposable project with synthetic file names and content. Remove user
    paths, session identifiers, prompts, credentials and customer data before
    committing a fixture. Document each replacement so the shape is preserved.
  • Add a relevant malformed-input or missing-policy case to the CLI fixture test.
  • Keep “CLI fixture passes” separate from “tested in host VERSION” in the guide.

Likely files

  • src/cli-format.test.ts
  • A small versioned fixture directory under src/fixtures/host-hooks/
  • docs/local-gateway.md, in “Use it in other agents”

Done when

  1. The fixture tests run without installing or contacting the host service.
  2. The guide contains a copyable configuration and the exact tested host version.
  3. Evidence shows the host blocked the harmless denied action and surfaced the
    denial reason; a zero exit from the CLI alone is not the host check.
  4. npm run build and npx vitest run src/cli-format.test.ts pass. Run the full
    npm test before submitting a behavior change.

This is a compatibility contribution, not a new hook framework or a claim of
coverage over other tool paths. Report suspected security bypasses privately
through SECURITY.md before publishing their details.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationhelp wantedExtra attention is needed

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions