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
24 changes: 16 additions & 8 deletions docs/CLAUDE_CODE.md

Large diffs are not rendered by default.

4 changes: 2 additions & 2 deletions docs/EXPERIMENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -145,12 +145,12 @@ The pilot itself runs a real model with a paid key: Class X (`AGENTS.md`). A nam
```bash
syberlabs start "Parse ISO dates with the UTC offset" --paths src tests --unattended
syberlabs experiment label --name githits-pilot --item LIB-1 --arm off --tag needs_lookup
syberlabs propose --claude-code --bare --allowed-tools Read,Edit,Write,Glob,Grep,WebSearch,WebFetch
syberlabs propose --claude-code --lane api-hooked --trusted-tree --allowed-tools Read,Edit,Write,Glob,Grep,WebSearch,WebFetch
syberlabs run --once # one safe step per thread; here, accepting the passing candidate

syberlabs start "Parse ISO dates with the UTC offset" --paths src tests --unattended
syberlabs experiment label --name githits-pilot --item LIB-1 --arm on --tag needs_lookup
syberlabs propose --claude-code --bare --allowed-tools Read,Edit,Write,Glob,Grep,WebSearch,WebFetch \
syberlabs propose --claude-code --lane api-hooked --trusted-tree --allowed-tools Read,Edit,Write,Glob,Grep,WebSearch,WebFetch \
--githits --githits-arm on # the only difference between the arms: the launcher and the skill
syberlabs run --once
```
Expand Down
1 change: 1 addition & 0 deletions spec/GAPS.md
Original file line number Diff line number Diff line change
Expand Up @@ -126,3 +126,4 @@ The schemas describe SyberWork as it behaves. They are not enforced at runtime e

63. **The GitHits pilot's example pacing and license reading rest on GitHits' documentation, not on observed traffic.** (1) The host paces `example` calls to one per 40 s per host (`syberlabs/githits_pace.py`, called by the launcher entry); GitHits' limit is per organization, so two hosts, or an operator's own `syberlabs githits example` (not paced), share the organization's budget without seeing each other's slots. (2) A loopback base URL is not paced unless `SYBERLABS_GITHITS_PACE_SECONDS` asks: a loopback proxy that forwards to GitHits would go unpaced. (3) Calls queued behind several others wait one interval each, so a Bash tool timeout shorter than the queue ends a call before it is sent, and the host then flags it `githits_unrecorded`. (4) The time file is plain text a process of the same user can rewrite; it paces cooperating processes and is no security boundary. (5) The license reading admits an example's `References`/`Sources` links by their `(SPDX)` and passes an example with neither code (a fenced, indented or HTML block) nor a source; inline code in prose is not read as code, and the three documented shapes (`complete`, `degraded`, `no_example` in the pinned OpenAPI document) are the only evidence of what real responses look like until the first live example is recorded. (6) The engineering smoke pins Claude Code 2.1.312 exactly because the host and the pilot VM run it; that version's flags were not re-checked here.
64. **The GitHits launcher fails closed before the network, and the treatment runs on a hooked API lane; neither is verified live, and other lookups on a `--bare` lane are still caught only after the fact.** The live canary of 2026-10-30 (Claude Code 2.1.312 on a Freestyle Linux VM) settled 56 (2): a `--settings` `PreToolUse` hook does not run under `--bare`, so `propose --claude-code --bare --githits` let the model run the launcher with no guard, and the client sent the lookup (`sent: true`) before the host stopped the run `provider_guard_inactive`. Now the launcher's entry sends nothing without claiming the hook's MAC-verified decision for its exact argv (`query_guard.claim_launch`; refused calls are recorded `status: unguarded`, `sent: false`), and `--githits` refuses `--bare` and runs on `--lane api-hooked` (the API key without `--bare`, a fresh `CLAUDE_CONFIG_DIR` and home per call, `--disable-slash-commands`; `docs/CLAUDE_CODE.md`). Not solved: (1) a decision is bound to the launcher's arguments (their SHA-256) and claimed once, not to a tool use id, which the launcher cannot see; a process holding the per-call key (a stdio MCP server, a shell under `--allow-code-tools-with-mcp`) can still sign a decision for its own arguments, as it could before; (2) the hook's words and the launcher's argv agree for plain words and quoted strings under a POSIX shell; a shell or platform that hands over different bytes (Git Bash's argument conversion to a Windows process, a non-UTF-8 byte) refuses a legitimate lookup (fail closed), which no live run has exercised; (3) WebSearch, WebFetch and `--mcp-config` (`mcp__githits__*`) lookups on a `--bare` lane have no pre-send gate: the hook does not run, so they still leave and are flagged `unguarded` afterwards; only `--githits` refuses `--bare`, and `api-hooked` or a login lane is where those tools are guarded; (4) `api-hooked` has run only against the stand-in `claude`: whether 2.1.312 with an empty config directory and home starts headless on `ANTHROPIC_API_KEY` (`apiKeySource`) and runs the hook is for its first live call, and the flags were read from 2.1.309's `--help` because 2.1.312's was not on the building machine; managed (policy) settings still load, `--setting-sources` has no value meaning `--settings` alone, `USERPROFILE` moves only on Windows, and the worktree's memory files (`CLAUDE.md`) are read in both arms, so the lane needs `--trusted-tree`; (5) the example license parser now reads any ATX or bold heading that names a source or reference ("## Source code" included) as a sources section and a fenced or indented block inside a blockquote as code, both of which can only drop more examples (fail closed); how often that drops a usable GitHits example is not measured; (6) the default deny-list (`SyberLabs`, `sykosyber`, `pypi:syberwork`, `deepwiki.com`, `deepwiki.org`) detects a fork of a SyberLabs repository only by its name (`githits.FORK_NAMES`) in a result's URL or a target, so a renamed fork, a vendored copy, or SyberLabs code mirrored under another name and site still passes, and no mirror or front-end other than DeepWiki is listed.
65. **`--bare` refuses the lookups no hook would screen there, the launcher keeps Git Bash from rewriting its arguments, and the eval spec refuses what the provider refuses; none of it is verified live.** `guard-lane-2` (2026-11-01) answers #155's verification. Built: a `--bare` provider whose allowed tools include `WebSearch` or `WebFetch` (`claude_code.web_tools`), or whose `--mcp-config` names an MCP server, is refused `invalid_provider` when built and pointed to `--lane api-hooked`, because Claude Code 2.1.312 runs no `--settings` hook under `--bare` and such a lookup would leave before it is flagged `unguarded`; `--allow-unscreened-bare` overrides and is recorded as `signal.guard.allow_unscreened_bare` (64 (3) is closed for every run without the override); the launcher exports `MSYS_NO_PATHCONV=1` and `MSYS2_ARG_CONV_EXCL='*'` before its `exec`, so Git Bash hands a word starting with `/` to the host's Python as typed (64 (2), for that conversion); `eval/arms.check` refuses, at spec validation, `githits` with `bare`, `bare` with `api-hooked`, `api` without `bare`, and `bare` with a web tool or any `mcp_config`; the cross-process pacing test asserts on the slot stamps each request took, not on arrival times. Not solved: (1) the override exists because the historical MCP A/B ran on `--bare`; a run that passes it is caught only after the fact, as before; (2) the eval spec has no override, and it refuses every `mcp_config` on `bare`, also one naming no server, which the provider would build; (3) the two variables are read from Git for Windows' and MSYS2's documentation and exercised against the Git Bash on the building machine and CI's Windows runner, not under Claude Code's own Bash tool on Windows, which is for the first live Windows call; a non-UTF-8 byte or another shell's conversion still refuses (fails closed); (4) a server tool Claude Code calls for itself (`web_search`, `web_fetch`) is refused on `--bare` only when its name is in `--allowed-tools`.
45 changes: 40 additions & 5 deletions syberlabs/claude_code.py
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,8 @@

syberlabs propose --claude-code --trusted-tree # the operator's login (subscription_local)
syberlabs propose --claude-code --bare # an API key in the environment (api)
syberlabs propose --claude-code --bare --mcp-config githits.json # the same, with one more MCP server
syberlabs propose --claude-code --lane api-hooked --trusted-tree # an API key, without --bare: hooks run
syberlabs propose --claude-code --lane api-hooked --trusted-tree --mcp-config githits.json # one more MCP server
syberlabs propose --claude-code --lane api-hooked --trusted-tree --githits # the same, with the GitHits launcher

``ClaudeCodeProvider`` is ``providers.RepairProvider`` with one call replaced: instead of a JSON adapter, each call
Expand Down Expand Up @@ -79,6 +79,14 @@
prove. ``allow_code_tools_with_mcp`` (``--allow-code-tools-with-mcp``) overrides, and is recorded as
``signal.guard.allow_code_tools_with_mcp``.

Unscreened lookups. Under ``--bare`` no ``--settings`` hook runs (``BARE_HOOKS``), so no lookup is screened before
it leaves: a ``WebSearch`` or ``WebFetch`` call, or a call to a server ``--mcp-config`` names (``mcp__githits__*``),
is sent and flagged ``unguarded`` only afterwards. A ``--bare`` provider whose allowed tools include ``WebSearch`` or
``WebFetch`` (``web_tools``), or whose ``--mcp-config`` names an MCP server (``names_mcp_server``), is therefore
refused when it is built (``invalid_provider``), pointing to ``--lane api-hooked``, where the hook runs.
``allow_unscreened_bare`` (``--allow-unscreened-bare``) overrides, and is recorded as
``signal.guard.allow_unscreened_bare``.

Credential lanes (bring your own credential: SyberLabs never stores, pools or forwards a credential; the operator's
own Claude Code runs under their own login, or with their API key). ``api`` (``--bare``, the default
there) is ``billed``: the tokens are priced under the contract's ``budget.prices`` through the host's meter, as an
Expand Down Expand Up @@ -271,6 +279,13 @@ def code_tools(tools: Sequence[str]) -> list[str]:
return [name for name in built_in_tools(tools) if name.lower() in named]


def web_tools(tools: Sequence[str]) -> list[str]:
"""The web lookup tools (``WEB_TOOLS``: ``WebSearch``, ``WebFetch`` and the server tools' names) among
``--allowedTools`` entries, a specifier dropped, compared ignoring case."""
named = {name.lower() for name in WEB_TOOLS}
return [name for name in built_in_tools(tools) if name.lower() in named]


def names_mcp_server(path: Path) -> bool:
"""False only for a JSON object whose ``mcpServers`` is absent or an empty object; a file that cannot be read
or parsed, or any other shape, counts as naming a server (fail closed)."""
Expand Down Expand Up @@ -311,14 +326,21 @@ def githits_skill() -> tuple[str, str]:

def launcher_text(python: str, entry: Path) -> str:
"""The launcher: a POSIX shell script (Claude Code's Bash tool runs bash, Git Bash on Windows) that replaces
itself with the host's Python running the host checkout's entry under ``-I``, with the call's arguments."""
itself with the host's Python running the host checkout's entry under ``-I``, with the call's arguments. It
first turns off Git Bash's (MSYS2's) argument conversion: handing a word that starts with ``/`` to a Windows
program, MSYS2 rewrites it as a Windows path (``/api/v1`` becomes ``C:/Program Files/Git/api/v1``), so the
launcher's argv would differ from the words the query guard's hook digested, and an honest lookup would be
refused. ``MSYS_NO_PATHCONV`` (Git for Windows) and ``MSYS2_ARG_CONV_EXCL='*'`` (MSYS2) both mean "convert
nothing"; any other shell ignores them."""
def quoted(path) -> str:
text = Path(path).as_posix()
if "'" in text or "\n" in text:
raise Rejected("provider_unavailable", "the host's Python or checkout path holds a quote or a newline")
return "'" + text + "'"
return ("#!/bin/sh\n# SyberLabs GitHits launcher for one Claude Code call: written by the host, read-only, removed "
"after the call.\n# It runs the host checkout's GitHits client, never the candidate worktree's.\n"
"# Git Bash would rewrite an argument starting with / for a Windows program; pass every word as typed.\n"
"export MSYS_NO_PATHCONV=1 MSYS2_ARG_CONV_EXCL='*'\n"
f"exec {quoted(python)} -I {quoted(entry)} \"$@\"\n")


Expand Down Expand Up @@ -653,7 +675,7 @@ def __init__(self, repo: Repo | str | Path, *, bare: bool = False, trusted_tree:
name: str = "claude-code", revision: str = "1", timeout: int = 1800, max_calls: int | None = None,
guard_max_lines: int | None = None, guard_max_chars: int | None = None,
allow_code_tools_with_mcp: bool = False, githits: bool = False, arm: str = "b",
thread_label: str | None = None):
thread_label: str | None = None, allow_unscreened_bare: bool = False):
lane = lane or ("api" if bare else "subscription_local")
if lane not in LANES:
raise Rejected("invalid_provider", "lane must be one of " + ", ".join(LANES))
Expand Down Expand Up @@ -727,6 +749,16 @@ def __init__(self, repo: Repo | str | Path, *, bare: bool = False, trusted_tree:
"inherits (the MCP server holds it already), and a code-running tool can read it and "
"sign a forged decision. Drop the tool, or pass --allow-code-tools-with-mcp to "
"accept that (recorded in signal.guard)")
if bare and not allow_unscreened_bare:
unscreened = web_tools(tools) + (["--mcp-config naming an MCP server"]
if mcp_config is not None and names_mcp_server(mcp_config) else [])
if unscreened:
raise Rejected("invalid_provider",
f"refusing {', '.join(unscreened)} with --bare: {BARE_HOOKS}. Under --bare the query "
"guard screens no lookup before it leaves; it is flagged unguarded only afterwards. "
f"Run these lookups where the guard's hook runs: --lane {HOOKED} --trusted-tree (the "
"API key), or a login lane. Or pass --allow-unscreened-bare to accept unscreened "
"lookups (recorded in signal.guard)")
try:
guard = query_guard.policy(guard_max_lines, guard_max_chars)
except ValueError as exc:
Expand All @@ -738,6 +770,7 @@ def __init__(self, repo: Repo | str | Path, *, bare: bool = False, trusted_tree:
self.mcp_config, self.allowed_tools, self.max_turns = mcp_config, tools, max_turns
self.guard = guard # host policy: {version, max_lines, max_chars}
self.allow_code_tools_with_mcp = bool(allow_code_tools_with_mcp) # the operator's override, on the signal
self.allow_unscreened_bare = bool(allow_unscreened_bare) # the operator's override, on the signal
self.lookups: list[dict] = [] # every lookup of every call, as recorded (digests, never query text)
self.version = self._installed_version()

Expand Down Expand Up @@ -830,7 +863,8 @@ def githits_environment(self, records: Path, record_key: str, session: str) -> d
(fresh per call), the host's example pacing directory (``SYBERLABS_GITHITS_PACE_DIR``: the operator's,
else the host's temporary-directory default, resolved here, so a launcher whose ``TMPDIR`` or home differs
still shares one pacing slot), the session and agent headers, and the license and exclusion policy as
explicit lists (the operator's, else the defaults; ``SYBERLABS_GITHITS_EXCLUDE`` only adds to ``SyberLabs``).
explicit lists (the operator's, else the defaults; ``SYBERLABS_GITHITS_EXCLUDE`` adds to the default
deny-list, ``githits.DEFAULT_EXCLUDE``, and never replaces it here).
The token is the operator's own ``GITHITS_API_TOKEN``, inherited, never written."""
licenses = githits_client.LicensePolicy.from_env(os.environ)
exclude = githits_client.Exclusions.from_env(
Expand Down Expand Up @@ -984,7 +1018,8 @@ def _call(self, space: SearchSpace, request: dict, parents: list[str]):
signal = {"lane": self.lane, "cost_basis": self.cost_basis,
"harness": {**transcript.harness(), "installed_version": self.version, "lane": self.lane},
"guard": {**self.guard, "policy_digest": hook_env[query_guard.POLICY_DIGEST_ENV],
**({"allow_code_tools_with_mcp": True} if self.allow_code_tools_with_mcp else {})}}
**({"allow_code_tools_with_mcp": True} if self.allow_code_tools_with_mcp else {}),
**({"allow_unscreened_bare": True} if self.allow_unscreened_bare else {})}}
if githits_signal is not None:
signal["harness"]["skill"] = {"path": SKILL_NAME, "sha256": self.skill[1]}
signal["githits"] = githits_signal
Expand Down
6 changes: 6 additions & 0 deletions syberlabs/cli.py
Original file line number Diff line number Diff line change
Expand Up @@ -176,6 +176,11 @@ def main(argv: list[str] | None = None) -> int:
help="for --claude-code: allow Bash or PowerShell in --allowed-tools although --mcp-config "
"names an MCP server (refused otherwise: the guard's key is in Claude Code's "
"environment); recorded in signal.guard")
propose.add_argument("--allow-unscreened-bare", action="store_true",
help="for --claude-code --bare: allow WebSearch or WebFetch in --allowed-tools, or an "
"--mcp-config naming an MCP server (refused otherwise: no --settings hook runs under "
"--bare, so those lookups leave unscreened; use --lane api-hooked); recorded in "
"signal.guard")
propose.add_argument("--githits", action="store_true",
help="for --claude-code: GitHits through the API client (arm B of the pilot): a per-call "
"launcher as the only Bash command, guarded, its records journaled as lookups, and the "
Expand Down Expand Up @@ -638,6 +643,7 @@ def _run(kit: Kit, args) -> int:
max_calls=args.max_calls, guard_max_lines=args.guard_max_lines,
guard_max_chars=args.guard_max_chars,
allow_code_tools_with_mcp=args.allow_code_tools_with_mcp,
allow_unscreened_bare=args.allow_unscreened_bare,
githits=args.githits, arm=args.githits_arm,
thread_label=thread.id if args.githits else None)
found = thread.propose(provider, seed=args.seed)
Expand Down
Loading
Loading