packet-ask

Korean

A local CLI that sends only a scrubbed packet to a SUB agent. The MAIN agent is whichever session you are in now.

It copies the files or diff you choose, scrubs them, then either runs an official CLI against that packet or prints packet.md to paste elsewhere.

This tool shrinks what you send on purpose. It does not guarantee no leakage and does not stop vendor training. Vendor terms still apply. See SECURITY.md (Korean).

MIT licensed. See LICENSE.

• PyPI: pypi.org/project/packet-ask
• Repository: github.com/ictechgy/packet-ask

Requirements

• Python 3.11+
• uv 0.10.9+ (same lower bound as uv_build in pyproject.toml)
• GLM / Claude SUB runs: a claude CLI on the allowlist path (origin signatures are not verified)
• Kimi runs: a kimi CLI on the allowlist path
• paste / grok / agy print a packet and do not launch a vendor. Run packet-ask doctor for the measured reason each one stays paste-only

Credentials come from a dedicated environment variable, a packet-ask-owned macOS Keychain item, or an explicitly requested one-run prompt. This tool does not read .env, ZCode, Claude Code, arbitrary key files, or key commands. Never put key values on the command line; they land in shell history. The same applies to the question: --question is argv and is visible in the process table and in shell history, so prefer --question-stdin. Stdin keeps the question out of argv, but it does not control what an interactive shell records; read a sensitive question from a file rather than a typed heredoc. Variable names are in env.example, and the complete source contract is in docs/key-sources.md. The executable allowlist is in SECURITY.md. Claude-family launches use official bare mode, an empty built-in tool set, and strict explicit empty MCP configuration. doctor only checks that bounded help text mentions those required flags; it does not prove an OS sandbox.

Install

uv tool install packet-ask
packet-ask install-skills
packet-ask doctor

If it is already installed, run uv tool upgrade packet-ask. pipx install packet-ask and pip install packet-ask in a venv also work.

From the GitHub default branch:

uv tool install git+https://github.com/ictechgy/packet-ask

Local checkout:

uv sync
uv run packet-ask doctor

install-skills writes SKILL.md to ~/.claude/skills/packet-ask, ~/.grok/skills/packet-ask, ~/.codex/skills/packet-ask, and ~/.agents/skills/packet-ask. Each home is attempted on its own. A home whose path contains a symlink, that holds a different SKILL.md without --force, or that cannot be read or written is skipped and reported on stderr while the other homes are still installed. Paths whose SKILL.md is current after the run go to stdout; a home that already matched the packaged skill is reported without being rewritten. The exit code is 13 when any home failed a confinement check, otherwise the first failure's code (2 for a different existing SKILL.md), otherwise 0. Here 13 means a confinement check failed during installation, not that a vendor process was skipped. After that, /packet-ask or a phrase like "review with kimi" should make MAIN call this CLI.

Scope

review and research are the only task commands. review requires one of the flags below. It does not send the whole working tree by default.

research does not attach local files or diffs by default. The only exception is --include-files. --diff and --staged are rejected.

inspect review and inspect research build and verify the same scrubbed packet but print metadata only after cleanup. They do not load a provider, inspect a credential, calculate a provider timeout, or launch a vendor. Human output is one escaped line; --json returns only the fixed packet summary fields. --breakdown additively reports scrubbed question bytes, framing bytes, and per-file/diff scrubbed bytes, logical lines, and allowlisted redaction counts. Line counts describe only the post-scrub payload, use LF as the separator, and are per-item only (0 for a zero-byte file). A diff count covers its complete rendered diff, including headers and hunks—not just changed lines. This per-item shape metadata is disclosed by design; the question and item body are never returned.

--preview builds and verifies the same scrubbed packet, then prints the launch plan and stops. It is the one surface that answers "what is about to go where": on top of the receipt fields it adds the provider mode, the credential source kind, the --max-bytes remainder, and launch: not-started.

packet-ask review --provider glm --preview --diff HEAD --question "Review this"
packet-ask preview provider=glm mode=review provider_mode=launch selector=diff paths=["changes.patch"] bytes=10374 sha256=ee792fb26412 budget_remaining=251770 timeout=1200s(auto,applies) credential=auto:keychain launch=not-started surface=absent guarantees=...

The credential is checked for existence only; its value is never read, because reading it would make a preview as dangerous as a run. No ledger line is written: an entry means a run reached the point of egress, and a preview never does. --preview with --dry-run is a usage error, since --dry-run prints the packet body and --preview never does.

--line-numbers opt-in adds a fixed-width gutter to scrubbed full-file content inside packet.md, so a review can cite packet-local lines. It does not alter the scrubbed files under files/, never decorates unified diffs, and counts all gutter/note bytes against --max-bytes. The numbers are stable only for the receipt's packet digest. With the flag off, packet bytes remain unchanged.

--selected-tree opt-in adds a deterministic tree made only from paths already selected by --files or --include-files. It never walks the repository, shows repeated selections once, renders ASCII-escaped labels in an inert fenced text block, and counts the tree against --max-bytes. Diff-only and question-only packets reject the flag instead of silently widening or ignoring its scope.

File section headings preserve ordinary Unicode paths but escape line/control, bidi, backtick, and HTML-delimiter characters. The private artifact under files/ keeps the exact selected filename.

--max-files applies to explicit files and diff paths. --max-bytes applies to the final UTF-8 packet.md, including framing and path labels. Reads stop at the configured bound, and explicit binary or non-UTF-8 files are rejected.

--preflight-timeout defaults to 30 seconds. One monotonic absolute deadline is shared by real-fd question stdin, worktree discovery, diff name-status, diff content, and packet-local git init; each Git call also keeps its existing 30-second cap. A supplied positive value is used exactly. Regular file reads and CPU redaction are bounded by size but are not forcibly preempted by this timer.

After normal redaction, verification also scans a detection-only Unicode shadow. NFKC-compatible characters, format controls, equivalent dots and dashes, and Unicode decimal digits can expose obfuscated international email or phone candidates. Known token families, secret literals, URL userinfo, and PEM headers are checked against the same shadow; canonical dotted Korean mobile numbers are scrubbed and mixed-separator forms fail closed. The packet text is never normalized or rewritten from this shadow; a candidate fails closed instead. Ambiguous Unicode matrix expressions with an unrecognized ASCII attribute-like suffix remain allowed to reduce code false positives, so this is still a denylist rather than a no-leak guarantee.

--effort selects how hard the vendor thinks. It is opt-in; omitting it leaves the vendor default. Value and origin are split the way timeout_seconds and timeout_source already are: effort is null and effort_source is vendor-default.

PACKET_ASK_EFFORT sets a default so you do not have to type the flag every time. --effort wins over it, and effort_source records which one applied (explicit, env, or vendor-default). Without that record you cannot later answer why one run took 751 seconds, and that record is the difference between a default and a silent default. An invalid value is rejected with exit 2 rather than falling back to the vendor default; argparse validates the flag only, so a typo in the variable would otherwise disappear. A blank value means unset.

Note the blast radius: the variable applies to every task run, and review and research share the same path. With it set, a --provider paste run is rejected with exit 2 rather than ignoring the default. That is consistent with the flag, but a variable lives in a shell profile and is easy to forget, so unset it or pass --effort deliberately when you switch to paste. Only the Claude-family launch providers (glm, claude) accept it; paste and kimi reject it instead of dropping it silently.

Measured on one packet and one question against glm:

About 2x per step up to high (1.98x, 2.07x), then 1.69x to max. The low-to-max multiplier holds at 20x the packet size (6.94x and 6.19x). Holding effort fixed, 20x more bytes cost only 1.20-1.35x. Output length is not the signal: high returned a shorter answer than medium. The time is spent reasoning, not writing. Each cell is a single sample.

If --timeout is omitted, launch providers use the larger of the packet-size tier and the effort tier (low/medium 1200 s, high 1800 s, xhigh/max 2700 s). Taking the larger of the two keeps a big packet from silently losing its existing ceiling. xhigh was not measured; it is grouped with max because it should fall between high and max. The packet size tiers are: up to 64 KiB gets 1200 seconds, up to 128 KiB gets 1500 seconds, and larger packets get 1800 seconds. A supplied --timeout is used exactly without clamping. The larger defaults do not delay successful calls; they only postpone failure for a real hang, which can still be interrupted with Ctrl+C. CI and unattended runs should set an explicit timeout. Paste and dry-run receipts show the resolved value as informational, but no provider deadline is applied.

Stated limits

Every success surface states its own limits. receipt and inspect summaries carry a fixed guarantees object — leakage: not-guaranteed, vendor_training: not-restricted, vendor_local_copy: uncontrolled, cwd_sandbox: none, redaction: denylist, doctor: help-text-only, policy_gate: lexical-tripwire, output_screen: lexical-tripwire — and the human receipt line ends with guarantees=leakage:not-guaranteed,vendor_training:not-restricted,vendor_local_copy:uncontrolled,cwd_sandbox:none,redaction:denylist.

These are code constants, not computed results. The disclaimer keys therefore cannot drift into a promise. Four keys assert that a mechanism exists (redaction, doctor, policy_gate, output_screen) and are additionally pinned to real behavior by tests, because a constant that outlives its mechanism would be a machine-readable falsehood. The human line carries every key except the three mechanism descriptors (doctor, policy_gate, output_screen) and is assembled from the same constant, so it cannot quote a stale value. redaction belongs to both groups on purpose: its value denylist is itself a limit statement. inspect never launches a vendor and still carries the vendor keys: the object lists the limits of the tool, not a measurement of one run. Read it together with that surface's own launch state.

This list is not exhaustive. It names the limits that are most often misread, not every risk. The failure envelope is unchanged and still carries only a fixed code, kind, and message.

doctor states its own verification level the same way. After the provider rows it prints a supervision state line and then one fixed line:

packet-ask supervision state=none
packet-ask doctor signals=verification:flags-mentioned,sandbox:none,signatures:not-checked

supervision state=external only means the host process supplied extra confined environment through the code hook; it does not verify an OS sandbox. The receipts carry the same state as a supervision field and a supervision=... token on the human line.

doctor runs before any receipt exists, so this is where the offset has to arrive. verification: flags-mentioned is pinned to real behavior; the other two say what doctor never attempted. It builds no sandbox and checks no signature or hash.

Both lines are append-only token sequences. Parse them by whitespace and key=value; do not anchor a regex to the end of the line. They are machine surfaces and do not change with PACKET_ASK_LANG.

Disclosure surface

The design says the user picks the packet. When a skill drives this CLI, the agent picks --files. The scope flags only stop "the whole tree by accident"; they do not stop "256 KiB the agent chose".

Commit a .packet-ask-surface file at the worktree root listing the path prefixes this repository may disclose:

# what this repository may send to a SUB
src
docs/public

With that file present, an explicit --files / --include-files path outside the declared prefixes is rejected with exit 11 before any vendor starts. Without the file, nothing changes. Matching is by path component, so src does not open srcret/. Absolute paths, .., globs, control characters, a symlinked declaration, and an empty declaration are all rejected.

--outside-surface overrides the check for one run, and the receipt, inspect summary, and ledger all record surface: overridden instead of enforced.

Diff paths are checked too. --diff <ref> can reach history without touching the worktree at all, so exempting diffs would leave a channel that changes nothing a reviewer would see.

What it does not do

This is not a leak-prevention allowlist and it is not a sandbox. Its only mechanism is that widening the scope requires editing a committed file, so the edit shows up in git status or as a new commit and lands in the review you already do.

• A declaration is about paths, not contents. Declaring src does not mean src holds no secrets; the redaction denylist still applies and still is a denylist.
• A hard link inside a declared prefix that points at a file outside it is accepted, because a hard link is the file and there is no original to prefer. Creating one is itself a visible worktree change.
• Content injected into an ordinary diff is not caught. The edit is visible, but far less salient than a change to the declaration file.
• A malformed declaration fails closed and --outside-surface does not bypass it. Fix the file.

Egress ledger

The receipt goes to stderr once and is gone with the scrollback. When a skill drives this CLI, the agent picks --files, so there is no surface left for a human to ask what actually went out.

Set PACKET_ASK_LEDGER to an absolute path and a task run appends two JSON lines: an egress line before the vendor starts and a result line once the response has settled. The egress line records a run that reached the point of egress, not a confirmed delivery — a vendor that fails afterwards still leaves an entry, which is the safe direction for an audit surface. It holds: timestamp, phase, mode, provider, selector, relative paths, bytes, packet digest, redaction counts, and the resolved timeout.

The result line pairs with it by packet digest and holds only timestamp, phase, mode, provider, digest, outcome, output_bytes, output_hint, and failure_code when the run failed. answered means the vendor returned output that passed the output guard — not that the process exits 0, since a cleanup warning can still follow. failed carries the exit code and nothing from vendor stderr. not-observable is a provider mode that does not launch — today paste, which --dry-run also forces: the answer never passes through this tool, so the packet it echoes back is not recorded as output. output_bytes is the sanitized response body in bytes, excluding the envelope framing. output_hint says the instruction-like tripwire fired; the phrase itself is never written.

Read a line without phase as an egress line (0.11.0 and earlier wrote none) and skip a phase you do not know: a result line carries no selector and no paths. Pair by digest and timestamp order. Two concurrent runs of the same packet can interleave, and then the file alone does not say which result belongs to which egress. An egress line with no result line means the run never reached a settled response — it was killed, it died outside the handled error paths, or the result append failed. The last case also prints a fixed warning on stderr, which is the only thing that distinguishes it from the first two.

The question, the file bodies, the vendor's answer, and vendor stderr are never written to either line.

packet-ask ledger summary reads the file back and prints counters only: entries (non-blank lines), egress, result, the three outcomes, unpaired_egress, hint_hits, skipped, both byte totals, and the first and last timestamp. Provider ids appear in --json only; the human line leaves them out so a user alias containing a space cannot break token splitting. Neither output ever prints paths, questions, or bodies, even though the egress lines hold relative paths. --json returns the same numbers as a packet-ask.v1 object. The command reads PACKET_ASK_LEDGER and exits 2 without it; it never creates the file. Reading checks the absolute path, rejects symlinks, requires a regular file owned by the current user, and stops at an 8 MiB cap instead of summarizing a prefix. It does not enforce the file mode and does not re-run the worktree check, because the summary carries no file content into any packet. A line that cannot be parsed, or that carries a phase, outcome, timestamp shape, or byte count this version does not accept, is counted in skipped rather than aborting the summary or being counted anyway. An egress line without a packet digest is never paired, so it always counts toward unpaired_egress.

The path must be absolute, must not be inside the git worktree, must not be a symlink, and must be owned by the current user. The worktree check compares device and inode, not path strings, so a case-insensitive filesystem does not bypass it. The file is opened O_APPEND, O_NOFOLLOW, and O_NONBLOCK, and its mode is forced to 0600 before the first write even if the file already existed. If the egress line cannot be written, the vendor does not run and the command exits 13. A ledger that silently skips entries is worse than none. The result line is not symmetric: by then the packet is already out and the answer is in hand, so a failed append prints a fixed warning on stderr and the run still succeeds — dropping your answer over opt-in bookkeeping would cost more. Leave the variable unset to keep the feature off.

Usage

packet-ask providers
packet-ask credentials status

# Store through the interactive macOS Keychain prompt; no key in argv/history
packet-ask credentials set glm --store macos-keychain --access command

# Question on stdin; it stays out of argv and the process table
packet-ask review --provider paste --files src/app.py --question-stdin <<'EOF'
Find race conditions in this code
EOF

# Packet only; do not launch a vendor
packet-ask review --provider paste --files src/app.py --question "Find race conditions in this code"
packet-ask review --provider paste --files src/app.py --json --question "Find race conditions in this code"

# Metadata only; no packet body, provider, or credential access
packet-ask inspect review --files src/app.py --question "Find race conditions"
packet-ask inspect review --diff HEAD --json --question "Review this change"
packet-ask inspect review --diff HEAD --breakdown --json --question "Size this packet"

# Increase only the local stdin/Git preflight budget; provider timeout is separate
packet-ask inspect review --diff HEAD --preflight-timeout 60 --question "Review this change"

# GLM. auto = dedicated env first, then packet-ask-glm in macOS Keychain
packet-ask review --provider glm --credential-source auto --diff HEAD --question "Review this change"

# Optional non-sensitive heartbeat every 30 seconds during provider launch
packet-ask review --provider glm --diff HEAD --progress --question "Review this change"

# Uncommitted working-tree diff. review without a scope flag is rejected
packet-ask review --provider paste --unstaged --question "Review this change"

# Anthropic Claude SUB. Key: PACKET_ASK_CLAUDE_KEY. Parent BASE_URL is unchanged
packet-ask review --provider claude --files src/app.py --question "Review this code"

# Kimi. Key: PACKET_ASK_KIMI_KEY
packet-ask review --provider kimi --files src/app.py --question "Review this code"

# grok/agy stay paste. grok resolves its real binary through the vendor home
# and takes no dedicated key; agy needs the task in argv
packet-ask review --provider grok --files src/app.py --question "Review this code"

# Research. Local files are off by default
packet-ask research --provider paste --question "What usually breaks in a Tailwind v4 migration?"

packet-ask doctor

# Counters only, from the opt-in ledger; no paths, no question, no bodies
packet-ask ledger summary
packet-ask ledger summary --json

Kimi is official kimi --quiet one-shot. It does not open an interactive session. It refuses to run without a resolved dedicated Kimi credential. Tools are disabled with a tools: [] agent file and a non-matching [tools] enabled list. KIMI_CODE_HOME is only the isolated profile ~/.config/packet-ask/providers/kimi/kimi-code. Do not run kimi in the real repo.

Kimi session cleanup must succeed before successful output is returned. If a provider, output-guard, or signal failure already exists, a simultaneous session cleanup failure is reported as a fixed non-sensitive warning and never replaces the original exception or exit status.

Kimi runs sharing the isolated KIMI_CODE_HOME are serialized by a private, non-inheritable advisory lock held through config creation, provider execution, and session cleanup. A second run that cannot acquire it within 30 seconds fails before touching the shared profile or launching a vendor.

GLM uses the official claude binary. It does not change the parent shell ANTHROPIC_BASE_URL. Only the child environment gets the Z.ai Claude Code endpoint and the resolved dedicated GLM credential. GLM and Claude use Claude Code's documented --bare and --tools "", plus an inline empty --mcp-config with --strict-mcp-config; the child also disables claude.ai MCP servers. Child environments set CLAUDE_CODE_DISABLE_AUTO_MEMORY, CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC, and DISABLE_ERROR_REPORTING. That reduces tool/config and local-session exposure. It does not prove an OS sandbox or that the vendor stores nothing.

Task commands default to --credential-source auto: the dedicated environment variable wins, then the canonical macOS Keychain item is tried. env, keychain, and prompt select exactly one source and never silently fall back. prompt requires an interactive terminal and never persists the value. Status checks Keychain item existence without retrieving its password. Resolved keys from every source are included in raw and terminal-normalized output guards. Task-time reads use fixed non-sensitive messages to distinguish a missing item, an inaccessible item, a timeout, an invalid value, and an indeterminate local read failure; JSON errors and code-level classification remain generic. These sources are selected through an immutable builtin backend registry; auto contains only env then keychain. There is no user backend registration, arbitrary command, key-file, or third-party settings adapter.

On success, stderr prints a receipt before launch (packet-ask receipt …) and millisecond phase times after (packet-ask timing …). --json adds a timing object. Neither line contains keys. Receipt paths are JSON escaped, and terminal control sequences are removed from untrusted provider output before it is printed. Explicit --progress adds only packet-ask progress phase=launch elapsed_ms=… to stderr every 30 seconds while the provider call is active. It is off by default, contains no provider/path/key/body data, and stops before final timing or success output.

With --json, argparse and runtime failures also return one packet-ask.v1 stdout object with ok: false and stable error.code, error.kind, and a generic English error.message. Raw argv, exception text, paths, keys, and tracebacks are excluded. The process exit code is unchanged. Without --json, the existing human stderr behavior remains unchanged.

Receipt JSON adds timeout_seconds, timeout_source (auto or explicit), and timeout_applies. The packet-ask.v1 schema is additive; consumers should ignore unknown receipt keys. The four-key millisecond timing object is unchanged.

Packet temp dirs live in the OS cache, not the git worktree. cwd is not a sandbox. A PACKET_ASK_CACHE_DIR inside the worktree is rejected. Every new packet holds a private lease; a later run removes packet data only when that lease is unlocked and at least 24 hours old. Active, fresh, symlinked, non-private, and legacy directories without a lease are not reaped. .gitignore entries for .packet-ask-tmp/ and packet.md only stop leftover files from being committed.

Every Git subprocess uses the same bounded process-group runner. Worktree discovery, diff collection, and packet-local git init share a deadline and byte limits. Ctrl+C, SIGTERM, and SIGHUP terminate registered Git/provider groups and run packet cleanup before propagating. Successful stdout is emitted only after packet cleanup succeeds. Packet payload bytes and digest, plus unchanged user provider overlays, are reused in-process to avoid repeated reads, hashes, and TOML parses.

User config ~/.config/packet-ask/providers.toml adds paste aliases only. It does not accept executables, argv, env, adapter IDs, launchers, probes, or registration hooks. Builtin launch dispatch and doctor probe kinds come from an immutable code registry. Alias labels and notes are bounded and reject terminal, bidi, and line/paragraph control characters before either human or JSON output. ZWNJ and ZWJ remain allowed for normal language and emoji sequences.

Exempting a path from the secret-name heuristic

Scope rejects paths whose name looks like a credential file. Part of that check is a guess: any path segment that is token, secret, password, credential, or passwd. In a repository where those words are domain vocabulary — token meaning context tokens, credential naming a redaction policy — the guess blocks ordinary source files.

~/.config/packet-ask/allowlist.toml exempts exact paths from that guess only:

version = 1
secret_name_exempt_paths = [
  "src/token_budget.py",
  "src/credential_policy.py",
]

What it does not do:

• It never exempts a credential file definition. .env and anything starting with it, id_rsa, id_ed25519, credentials, credentials.json, and the .pem .key .p12 .pfx .env .npmrc .pypirc .netrc suffixes stay rejected even when listed.
• It takes exact worktree-relative paths, not globs. One src/** line turning the whole rule off is the thing this control exists to prevent.
• It does not relax content redaction. The allowlist says a path may be read, not that its bytes may be sent unedited.

A malformed file is rejected rather than ignored, so a typo cannot silently drop your exemption. When a packet actually uses one, secret_name_exempt_used appears in the receipt, the JSON summary, and the preview line — the receipt does not hide that this packet was scoped wider than the default denylist. Set PACKET_ASK_ALLOWLIST_FILE to point somewhere else.

The implementation/incident question gate is a conservative lexical check, not a proof of intent. A rephrased request passes it, and a question that only asks for a review is also blocked when it contains one of the listed words; the rejection message says both. Negations are deliberately not interpreted. Launch adapters disable vendor tools and use the packet as the child cwd, but this is not OS-level filesystem confinement.

version = 1
[providers.gemini]
label = "Gemini CLI"

Skills

packet-ask install-skills installs into harness homes. The skill only tells MAIN to call packet-ask. Packet selection and vendor-tool disabling are enforced by the CLI; they are not an OS sandbox.

Exit codes

10–14 mean the vendor process was never started. Task termination preserves the conventional signal exit status: SIGHUP is 129, SIGINT is 130, and SIGTERM is 143.

install-skills reuses these codes for installation, not for a launch. There 13 means a confinement check failed while installing (a symlinked path, or an existing SKILL.md that could not be read or written) and 2 means a home holds a different SKILL.md and --force was not given. No vendor process is involved either way.

ledger summary reuses them for reading. There 2 means PACKET_ASK_LEDGER is unset, 13 means the ledger failed a read check (symlink, not a regular file, or not owned by the current user), and 14 means it is larger than the summary cap. No vendor process is involved.

Development

uv sync --group dev
uv run pytest

The current confinement hardening rationale is in docs/hardening.md. Runtime/process and hot-path decisions are in docs/runtime-hardening.md.

See CONTRIBUTING.md.

License

MIT Copyright (c) 2026 Coden