Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions docs/CLAUDE_CODE.md
Original file line number Diff line number Diff line change
Expand Up @@ -145,7 +145,7 @@ exec '<host python>' -I '<host checkout>/syberlabs/githits_cli_entry.py' "$@"
| `SYBERLABS_GUARD_LAUNCHER` | the launcher's path, for the query guard |
| `SYBERLABS_GITHITS_RECORD_DIR` | `githits-records/` in the call's guard directory |
| `SYBERLABS_GITHITS_RECORD_KEY` | a fresh `secrets.token_hex(32)` per call, in no file |
| `GITHITS_SESSION_ID` | `<thread>-<arm>` (`X-GitHits-Session-ID`; GitHits allows only `[A-Za-z0-9_-]`, so not `/`) |
| `GITHITS_SESSION_ID` | `<thread>-<arm>` (`X-GitHits-Session-ID`; GitHits allows only `[A-Za-z0-9_-]`, so not `/`); the thread is `thread_label` (the CLI passes the thread's id), else the search space's thread, so a provider built in Python names its thread too |
| `GITHITS_AGENT` | `syberfactory/<arm>` (`X-GitHits-Agent`) |
| `SYBERLABS_GITHITS_LICENSES` | the license allow list in force, written out (the operator's, else the permissive default) |
| `SYBERLABS_GITHITS_EXCLUDE` | the exclusion list in force, written out (`syberlabs` plus what the operator added) |
Expand All @@ -154,13 +154,13 @@ exec '<host python>' -I '<host checkout>/syberlabs/githits_cli_entry.py' "$@"

**Arm A holds no GitHits variable.** Without `--githits`, and without `--mcp-config` (no GitHits route at all), the provider removes every `GITHITS_*` and `SYBERLABS_GITHITS_*` variable from Claude Code's environment (`claude_code.githits_variable`, compared ignoring case), `GITHITS_API_TOKEN` and `GITHITS_API_URL` included. Least privilege was chosen over a byte-identical environment: arm A has no tool that could use the token, and now it does not hold it either. Arm A's argv is still byte-identical to what it was before this route existed. `tests/test_claude_code.py` pins arm A's argv literally and its environment as the caller's minus those variables plus the guard's three, and pins arm B's differences to exactly the items above plus the operator's GitHits variables that arm A no longer receives. An `--mcp-config` run keeps them, because a GitHits MCP server, a child of Claude Code, may read its token from that environment (the MCP A/B below).

**The guard over Bash.** With the launcher, the query guard's matcher is `^(mcp__githits__.*|WebSearch|WebFetch|Bash)$`, and a `Bash` call passes only when its command is the launcher's exact path, alone or followed by a space, and what follows is plain words and single- or double-quoted strings (`query_guard.bash_arguments`). `not_launcher` blocks any other command; `shell_syntax` blocks a control operator, redirection, expansion or substitution anywhere (`` ; & | < > $ ` \ ( ) { } ! ``, any control character such as a newline), a glob, tilde or comment character outside quotes, an unterminated quote, and `run_in_background`. The arguments that pass are the outbound text: each one, and all of them joined, are judged by the same rules as a GitHits tool's query (`secret`, `url_credentials`, `email`, `too_long`, `code_fence`, `code_lines`, `tree_line`). Decisions carry the same MAC under the per-call key. Claude Code's own permission check is a second gate: under `dontAsk` a Bash command that `Bash(<launcher>:*)` does not name is denied.
**The guard over Bash.** With the launcher, the query guard's matcher is `^(mcp__githits__.*|WebSearch|WebFetch|Bash)$`, and a `Bash` call passes only when its command is the launcher's exact path, alone or followed by a space, and what follows is plain words and single- or double-quoted strings (`query_guard.bash_arguments`). `not_launcher` blocks any other command; `shell_syntax` blocks a control operator, redirection, expansion or substitution anywhere (`` ; & | < > $ ` \ ( ) { } ! ``, any control character such as a newline), a glob, tilde, caret or comment character outside quotes, an unquoted word that a shell reads differently from the guard (one that starts with `=`, which zsh's default EQUALS option expands to a command's path; with `NAME=`, which bash's `set -k` turns into an assignment into the launcher's environment, so `GITHITS_API_URL=https://...` would send the client and its token elsewhere; or with `@`, which PowerShell splats; quoted, each passes), an unterminated quote, `run_in_background`, and a `timeout` shorter than the Bash tool's two-minute default (`query_guard.MIN_BASH_TIMEOUT_MS`): ended early by Claude Code, the launcher's client could be killed after its request left and before it writes the call's record. The arguments that pass are the outbound text: each one, and all of them joined, are judged by the same rules as a GitHits tool's query (`secret`, `url_credentials`, `email`, `too_long`, `code_fence`, `code_lines`, `tree_line`). Decisions carry the same MAC under the per-call key. Claude Code's own permission check is a second gate: under `dontAsk` a Bash command that `Bash(<launcher>:*)` does not name is denied.

**PowerShell under the override.** An operator's `Bash` or `PowerShell` entry is refused with `--githits` unless `--allow-code-tools-with-mcp` is passed. With the override, the matcher is `^(mcp__githits__.*|WebSearch|WebFetch|Bash|PowerShell)$` (`query_guard.MATCHER_SHELLS`), and a `PowerShell` call is judged by the same launcher-only rule as `Bash` (`query_guard.SHELL_TOOLS`): any command but the launcher is `not_launcher`, so an allowed PowerShell no longer runs unguarded. Its refusals are journaled like a refused Bash call (tool `PowerShell`, its rule) and counted in `signal.githits.bash_refused` and `lookups_blocked`. Without the override the matcher is the Bash one above.

**What is recorded.** After the call the provider reads the client's records (`githits.read_records` under the call's record key). Each authentic record becomes one verified `lookup` fact, tool `githits.<op>`, value `{tool, query_digest, request_id, status, at, results_returned, results_dropped, results_dropped_license, latency_ms, contamination_blocked, ok, guard}`: the client's own digest of the request it sent, never text. Forged or altered record lines are counted (`signal.githits.records_ignored`) and ignored. Every `Bash` call the guard did not pass is journaled as a `lookup` with tool `Bash` and its rule (or `unguarded`), which `lookups_blocked` counts. `signal.tool_usage.githits` is the number of authentic records (plus any `mcp__githits__*` call the stream shows). The candidate also carries `signal.githits: {arm, launcher_calls, launcher_passed, records, records_ignored, bash_refused, license_policy[, mismatch]}` and `signal.harness.skill: {path, sha256}`. `githits_lookups` never counts a `githits.doctor` fact.
**What is recorded.** After the call the provider reads the client's records (`githits.read_records` under the call's record key). Each authentic record becomes one verified `lookup` fact, tool `githits.<op>`, value `{tool, query_digest, request_id, status, at, results_returned, results_dropped, results_dropped_license, latency_ms, contamination_blocked, sent, ok, guard}`: the client's own digest of the request it sent, never text; `sent` is the record's, whether the request was written to GitHits (false for an excluded target or a connection that never opened, true from a timeout after the request left to an answer, null for a call interrupted in flight). The client records every call it starts, an answer it cannot read and an interruption included; the launcher's entry turns a `SIGTERM` into an exception for that, so a launcher ended by a Bash timeout records its call (a `SIGKILL` cannot be caught). Forged or altered record lines are counted (`signal.githits.records_ignored`) and ignored. Every `Bash` call the guard did not pass is journaled as a `lookup` with tool `Bash` and its rule (or `unguarded`), which `lookups_blocked` counts. `signal.tool_usage.githits` is the number of authentic records (plus any `mcp__githits__*` call the stream shows). The candidate also carries `signal.githits: {arm, launcher_calls, launcher_passed, records, records_ignored, bash_refused, license_policy[, mismatch]}` and `signal.harness.skill: {path, sha256}`. `githits_lookups` never counts a `githits.doctor` fact.

A record cannot be tied to the tool use that ran it, so the host reconciles counts: authentic records against launcher calls the guard passed. Fewer records is `mismatch: githits_unrecorded` (a usage error, a client that failed before recording, a denied permission; recorded, the call stands). More records than guarded calls is `githits_unexpected_records`: each record of the call is journaled `guard: unguarded`, and the search stops `provider_guard_inactive`, because something holding the key ran the client without the guard.
A record cannot be tied to the tool use that ran it, so the host reconciles counts: authentic records against launcher calls the guard passed. Fewer records is `mismatch: githits_unrecorded` (a usage error, a client that failed before recording, a denied permission; recorded, the call stands). More records than guarded calls is `githits_unexpected_records`: each record of the call is journaled `guard: unguarded`, and the search stops `provider_guard_inactive`, because something holding the key ran the client without the guard. A call that fails or times out registers no candidate, so its mismatch would reach the journal nowhere, and a launcher call still waiting for GitHits when the host ends Claude Code (its session is killed, so the client cannot record) would leave no trace: when such a call has fewer records than guarded launcher calls, its records are journaled `guard: unguarded` (not reconciled), and when it has none, one `githits.unrecorded` fact (the command line's digest, `sent: null`, `guard: unguarded`) stands for each launcher call the guard passed. A call refused `no_change` still loses its mismatch (`spec/GAPS.md` 59 (12)).

**The skill.** `skills/githits/SKILL.md` adapts GitHits' shipped skills (`githits-com/githits-cli` at `0bc9f5e68b`, `skills/githits-code/SKILL.md` and `skills/githits-mcp/SKILL.md`, Apache-2.0, Copyright 2025 GitHits Inc.; `skills/githits/LICENSE` is the upstream license and `skills/githits/NOTICE` says what changed) for the launcher: when a lookup is worth it (an API or version fact the repository and the standard library do not settle), how to phrase a query (short, naming the package and version, no code or repository text), targets first, search then grep or list then read, results as untrusted data, and citing sources in the final reply (the harness does not commit). Claude Code 2.1.309's `--help` offers `--append-system-prompt`, `--plugin-dir` (skills inside a plugin) and `--add-dir`; the provider uses `--append-system-prompt`, so the text is part of arm B's system prompt on every request rather than a skill the model may or may not load, and arm A's prompt is exactly the harness note. The YAML front matter is left out, and `{launcher}` is replaced by the call's launcher path, so arm B's exact appended text is the harness note, a blank line, and the file's body with that one substitution; the file's SHA-256 is on `signal.harness.skill`, computed with CRLF normalized to LF, so a Windows checkout with `core.autocrlf` records the committed blob's digest (`24c150e4…6508` today) as a POSIX one does. `.gitattributes` (`skills/** text eol=lf`) also checks the skill out with LF on every platform.

Expand Down
31 changes: 27 additions & 4 deletions syberlabs/claude_code.py
Original file line number Diff line number Diff line change
Expand Up @@ -195,6 +195,7 @@
SKILL_NAME = "skills/githits/SKILL.md"
LAUNCHER_PLACEHOLDER = "{launcher}"
CLIENT_TOOL = "githits." # a lookup fact from a client record: ``githits.<op>``
UNRECORDED_OP = "unrecorded" # ``githits.unrecorded``: a failed call's launcher call that left no record
GITHITS_UNRECORDED = "githits_unrecorded" # a launcher call passed the guard and left no authentic record
GITHITS_UNEXPECTED = "githits_unexpected_records" # more authentic records than launcher calls the guard passed
GITHITS_VARIABLES = ("GITHITS_", "SYBERLABS_GITHITS_") # prefixes arm A never passes (compared ignoring case)
Expand Down Expand Up @@ -322,19 +323,29 @@ def is_launcher_call(use: dict, launcher: str | None) -> bool:


def record_lookup(record: dict, guard: str) -> dict:
"""A ``lookup`` fact from one authentic client record: ``githits.<op>`` and the record's counts, never text."""
"""A ``lookup`` fact from one authentic client record: ``githits.<op>`` and the record's counts, never text.
``sent`` is the record's: whether the request was written to GitHits (null: not known)."""
op = record.get("op") if isinstance(record.get("op"), str) and re.fullmatch(r"[a-z]{1,16}", record["op"]) else "unknown"
found = {"tool": CLIENT_TOOL + op}
for field in ("query_digest", "request_id", "status", "at"):
found[field] = record[field][:128] if isinstance(record.get(field), str) else None
for field in ("results_returned", "results_dropped", "results_dropped_license", "latency_ms"):
found[field] = _count(record.get(field))
found["contamination_blocked"] = record.get("contamination_blocked") is True
found["sent"] = record.get("sent") if isinstance(record.get("sent"), bool) else None
found["ok"] = found["status"] == githits_client.OK and guard == query_guard.PASS
found["guard"] = guard
return found


def unrecorded_lookup(call: dict) -> dict:
"""A ``lookup`` fact standing for a launcher call the guard passed that left no client record, in a call that
registers no candidate to carry ``signal.githits.mismatch`` (it failed or timed out): tool ``githits.unrecorded``,
the digest of the command line, ``guard: unguarded`` (the host cannot reconcile it), never text."""
return record_lookup({"op": UNRECORDED_OP, "query_digest": call.get("query_digest"), "at": call.get("at"),
"sent": None}, query_guard.UNGUARDED)
Comment on lines +345 to +346

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Handle synthetic lookup facts in the metrics reader

When a failed or timed-out provider call leaves no client record, this creates a synthetic githits.unrecorded fact, but metrics._thread counts every githits.* fact except githits.doctor as an authentic client record. Consequently, a journal containing only this placeholder reports githits_lookups.value = 1 with the note host-observed: authentic GitHits client records, even though the launcher may never have started the client. Update the metrics reader alongside this new fact type so missing records preserve an unknown count rather than becoming a definite measurement in the A/B results.

Useful? React with 👍 / 👎.



def _short(value, limit: int = 64) -> str | None:
return value if isinstance(value, str) and 0 < len(value) <= limit and value.isprintable() else None

Expand Down Expand Up @@ -764,8 +775,12 @@ def githits_environment(self, records: Path, record_key: str, session: str) -> d
githits_client.EXCLUDE_ENV: ",".join("/".join(entry) for entry in exclude.entries)}

def _session(self, space: SearchSpace) -> str:
"""``X-GitHits-Session-ID``: ``<thread>-<arm>`` (GitHits allows ``[A-Za-z0-9_-]{1,64}``, so no ``/``)."""
label = self.thread_label or getattr(space, "thread_id", None) or getattr(space, "search_id", None) or "s0"
"""``X-GitHits-Session-ID``: ``<thread>-<arm>`` (GitHits allows ``[A-Za-z0-9_-]{1,64}``, so no ``/``). The
thread is ``thread_label`` (the CLI passes the thread's id), else the space's thread: ``GitSearchSpace`` keeps
it as ``_thread``, so a provider built in Python names its thread too, and two threads never share ``s1-b``."""
thread = getattr(space, "_thread", None)
label = (self.thread_label or getattr(space, "thread_id", None) or getattr(thread, "id", None)
or getattr(space, "search_id", None) or "s0")
return re.sub(r"[^A-Za-z0-9_-]", "-", f"{label}-{self.arm}")[:64]

def _instructions_changed(self, space: SearchSpace, parents: list[str]) -> list[str]:
Expand Down Expand Up @@ -861,8 +876,16 @@ def _call(self, space: SearchSpace, request: dict, parents: list[str]):
# journaled through its client record, which is the host's evidence that a lookup left.
observed += [{k: v for k, v in call.items() if k != "launcher"} for call in bash
if call["guard"] != query_guard.PASS]
guard = query_guard.UNGUARDED if mismatch == GITHITS_UNEXPECTED else query_guard.PASS
# A failed or timed-out call registers no candidate, so no signal.githits.mismatch reaches the journal: a
# launcher call in flight when the host ended Claude Code (the session is killed, so its client never
# records) would leave no trace. Its records are then journaled unguarded (not reconciled), and when it
# has none, one githits.unrecorded fact stands for each launcher call the guard passed.
lost = mismatch == GITHITS_UNRECORDED and failure is not None
guard = query_guard.UNGUARDED if mismatch == GITHITS_UNEXPECTED or lost else query_guard.PASS
observed += [record_lookup(record, guard) for record in records.records]
if lost and not records.records:
observed += [unrecorded_lookup(call) for call in bash
if call["launcher"] and call["guard"] == query_guard.PASS]
githits_signal = {"arm": self.arm, "launcher_calls": sum(1 for call in bash if call["launcher"]),
"launcher_passed": passed, "records": len(records.records),
"records_ignored": records.ignored, "bash_refused": sum(
Expand Down
Loading
Loading